The DarkMod Wiki - User contributions [en]

Setting Reverb Data of Rooms (EAX)

2026-01-25T00:26:23Z

Frost Salamander: /* Location Entity Method */

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 [https://github.com/kcat/openal-soft openal-soft]) without any requirements on sound card.

= General =

== Setup ==

EFX for a fan mission can be configured with or without a configuration file. However, fileless configuration is only supported for [[Setting_Reverb_Data_of_Rooms_(EAX)#Presets_(Version_2)|EFX presets]].

== EFX file ==
The EFX info for a map should be stored in the file "<tt>efxs/<mapname>.efx</tt>", 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 "<tt>OpenAL EFX</tt>" in sound settings in the main menu, otherwise TDM won't even try to load the 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:
* <tt>Version 1</tt> was supported by TDM from the very beginning. It uses some non-standard terms and quantities, which makes it hard to work with.
* <tt>Version 2</tt> 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 <tt>reverb</tt> keyword for Version 1 definitions, and <tt>eaxreverb</tt> 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 "<tt>name</tt>" 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 <tt>_area<num></tt> (where <num> is the portal area number), e.g. <tt>_area15</tt>.
'''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 "<tt>reloadSounds</tt>" 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 "<tt>no_efx</tt>" 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 "<tt>reloadDecls</tt>" 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 "<tt>no_efx</tt>" keyword (see issue [http://bugs.thedarkmod.com/view.php?id=4688 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 [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#95 OpenAL Effects Extension Guide](pages 95-101).
The short list is also available in a table on [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#66 page 66 of the guide]:

[[File:Eaxreverb_properties_screenshot.png|500px]]

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

== Presets (Version 2) ==
Presets can be set in 2 ways:
* As of TDM 2.13, the '''efx_preset''' spawnarg on the location entity for the location where you want to use the effect.
* in the .efx file

=== Location Entity Method ===
If you only plan on using presets, this is the recommended method as it's less complex and error-prone. On the location entity where you want to use the preset, set the spawnarg '''efx_preset''' to the value of the preset. For example:

<pre>
efx_preset CITY_SUBWAY
</pre>

If using this method no .efx file is required at all, but using both methods simultaneously is supported. In the case that both are used to set the preset value for a single location, the spawnarg value will take precedence.

=== File Method ===

There is one special property <tt>PRESET</tt>, 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.

=== Preset Values ===
The presets were taken from OpenAL-Soft implementation which TDM uses.
Here is the full list of preset names:

<pre style="height:350px; overflow:scroll;">
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
</pre>

Their definitions can be seen in [https://github.com/kcat/openal-soft/blob/master/include/AL/efx-presets.h efx-presets.h] from OpenAL-Soft source code.

<div class="mw-collapsible mw-collapsed" data-expandtext="Show" data-collapsetext="Hide">

== 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.

<div class="mw-collapsible-content">

* '''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:

{| style="margin: 0.5em; margin-left: 2em; border: 1px solid #a0a0a0; text-align: right; border-collapse: collapse;" cellpadding="2" border="1"

|-
!bgcolor="#ffdead"|Flag decimal
!bgcolor="#ffdead"|Flag binary
!bgcolor="#ffdead"|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.
</div>
</div>

=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=

See the "EFX Reverb" column of '''[[Fan_Missions_for_The_Dark_Mod|Fan Missions page]]'''. Missions with "Yes" have EFX Reverb.
<br>Most missions use v2.0 presets but a few missions such as "Volta and the Stone" and Behind Closed Doors use v1.0 settings.

=See Also=

The Version 2 definitions were implemented due to [http://bugs.thedarkmod.com/view.php?id=4815 issue 4815], it has some brief explanation.

A tutorial based around EFX can be found [http://forums.thedarkmod.com/topic/19205-getting-started-with-the-efx-room-reverb-system-wip/ here]

An old demonstration map of EAX in TDM is included [http://forums.thedarkmod.com/topic/11045-environmental-audio-extensions-eax-in-tdm/ here]

A discussion about no_efx is [http://forums.thedarkmod.com/topic/19213-efx-discussion here]

The first version of this article was written by Ishtvan [https://forums.thedarkmod.com/index.php?/topic/2071-setting-reverb-data-in-new-soundengine-wiki/ here]

[[Category:Sound]]
[[Category:Tutorial]]

Setting Reverb Data of Rooms (EAX)

2026-01-25T00:25:25Z

Frost Salamander: /* Presets (Version 2) */

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 [https://github.com/kcat/openal-soft openal-soft]) without any requirements on sound card.

= General =

== Setup ==

EFX for a fan mission can be configured with or without a configuration file. However, fileless configuration is only supported for [[Setting_Reverb_Data_of_Rooms_(EAX)#Presets_(Version_2)|EFX presets]].

== EFX file ==
The EFX info for a map should be stored in the file "<tt>efxs/<mapname>.efx</tt>", 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 "<tt>OpenAL EFX</tt>" in sound settings in the main menu, otherwise TDM won't even try to load the 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:
* <tt>Version 1</tt> was supported by TDM from the very beginning. It uses some non-standard terms and quantities, which makes it hard to work with.
* <tt>Version 2</tt> 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 <tt>reverb</tt> keyword for Version 1 definitions, and <tt>eaxreverb</tt> 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 "<tt>name</tt>" 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 <tt>_area<num></tt> (where <num> is the portal area number), e.g. <tt>_area15</tt>.
'''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 "<tt>reloadSounds</tt>" 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 "<tt>no_efx</tt>" 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 "<tt>reloadDecls</tt>" 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 "<tt>no_efx</tt>" keyword (see issue [http://bugs.thedarkmod.com/view.php?id=4688 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 [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#95 OpenAL Effects Extension Guide](pages 95-101).
The short list is also available in a table on [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#66 page 66 of the guide]:

[[File:Eaxreverb_properties_screenshot.png|500px]]

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

== Presets (Version 2) ==
Presets can be set in 2 ways:
* As of TDM 2.13, the '''efx_preset''' spawnarg on the location entity for the location where you want to use the effect.
* in the .efx file

=== Location Entity Method ===
On the location entity where you want to use the preset, set the spawnarg '''efx_preset''' to the value of the preset. For example:

<pre>
efx_preset CITY_SUBWAY
</pre>

If using this method no .efx file is required at all, but using both methods simultaneously is supported. In the case that both are used to set the preset value for a single location, the spawnarg value will take precedence.
=== File Method ===

There is one special property <tt>PRESET</tt>, 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.

=== Preset Values ===
The presets were taken from OpenAL-Soft implementation which TDM uses.
Here is the full list of preset names:

<pre style="height:350px; overflow:scroll;">
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
</pre>

Their definitions can be seen in [https://github.com/kcat/openal-soft/blob/master/include/AL/efx-presets.h efx-presets.h] from OpenAL-Soft source code.

<div class="mw-collapsible mw-collapsed" data-expandtext="Show" data-collapsetext="Hide">

== 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.

<div class="mw-collapsible-content">

* '''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:

{| style="margin: 0.5em; margin-left: 2em; border: 1px solid #a0a0a0; text-align: right; border-collapse: collapse;" cellpadding="2" border="1"

|-
!bgcolor="#ffdead"|Flag decimal
!bgcolor="#ffdead"|Flag binary
!bgcolor="#ffdead"|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.
</div>
</div>

=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=

See the "EFX Reverb" column of '''[[Fan_Missions_for_The_Dark_Mod|Fan Missions page]]'''. Missions with "Yes" have EFX Reverb.
<br>Most missions use v2.0 presets but a few missions such as "Volta and the Stone" and Behind Closed Doors use v1.0 settings.

=See Also=

The Version 2 definitions were implemented due to [http://bugs.thedarkmod.com/view.php?id=4815 issue 4815], it has some brief explanation.

A tutorial based around EFX can be found [http://forums.thedarkmod.com/topic/19205-getting-started-with-the-efx-room-reverb-system-wip/ here]

An old demonstration map of EAX in TDM is included [http://forums.thedarkmod.com/topic/11045-environmental-audio-extensions-eax-in-tdm/ here]

A discussion about no_efx is [http://forums.thedarkmod.com/topic/19213-efx-discussion here]

The first version of this article was written by Ishtvan [https://forums.thedarkmod.com/index.php?/topic/2071-setting-reverb-data-in-new-soundengine-wiki/ here]

[[Category:Sound]]
[[Category:Tutorial]]

Doors

2025-11-08T11:16:15Z

Frost Salamander: /* Automatically Removing Keys from Player Inventory After Use */

{{todo}}
''Written by Fidcal'' ''edit Baddcog''

==Quick Summary==

Quick way to get an unlocked door in your map:

* Insert one of the prefab doors complete with handles and select its skin property and click the button to change its skin appearance to whatever you want. Set any other properties you need.

Alternatively,

* Create a door from the entity list
* Use the "skin" spawnarg on the door to change its appearance.
* Create a handle from the entity list
* Add the ''door_handle'' property to the door and give it the name of the handle
* To the door handle add the value frob_peer and use the name of the door.
* To open clockwise, change the ''rotate'' property from <code>0 90 0</code> to <code>0 -90 0</code>

==Introduction==

This tutorial explains how to put doors into your map using Dark Radiant, as well as adjust them and their properties.

The rest of this tutorial assumes that you have a basic understanding of using DarkRadiant. If you haven't done so, please go read the [[Dark Radiant Must Know Basic Intro]] article first.

Additionally:

* Up, down, right, and left in Dark Radiant's ''top'' orthoview are regarded here as the standard map directions of North, South, East, and West where useful for clarity.
* Where the term ''brush'' is used with a door it mostly also applies to a door made up of a group of brushes and/or patches.
* Where the term ''door'' is used it often will also apply to any object you wish to rotate when frobbed, for instance an openable window, box lid, or even more exotic objects that the imaginative mapper might conceive like a signal, engine part, toy, or whatever. So long as it needs to turn or slide just a fixed amount when frobbed then return when frobbed again then the following applies.

==Door types==

All tangible objects in Dark Mod are ''entities'', having either a pre-made model shape or else brush/patch(es). So there are two ways to create a door in Dark Radiant: as a model door or a textured brush door (or a hybrid of the two).

Models are ready made door objects but cannot within Dark Radiant (at the time of writing) be resized, rescaled, cropped or clipped whereas brushes are very flexible in that respect and can be worked into custom shapes for your map, including secret doors that blend into walls and other surfaces.

Most of the current door models are found in two places along with the door handles.
*Model Viewer: doors created from here will be static in the world and have no props other than material type.
You can add any props to them to make them working doors. If nothing else it is a good place to view the different size and skin options for the doors.
*Entity List: most of the door models can be found here. These doors have properties already assigned so they are ready to be used. Only one base door of each type is listed, create the size/hinge count door you want (2 hinge doors have a 'no hinge' skin). You can choose a skin for the door once it has been created in the editor with the "skin" spawnarg (use the model name of the door you want, taken from the model list, as its value). This is the easiest way to create a door. The same goes for door handles.

Remember also that door functions may be applied to objects other than doors, such as openable windows, drawbridges, gates, etc. In fact, anything that needs a partial rotation or slide when frobbed then return when frobbed again, such as a signal device. Lockboxes and chests use similar properties.

You can create one door/handle set and copy/paste it, but you need to take great care that all the name props are changed to match in each clone. Otherwise you get handles that fly off when a distant door moves, and handles that don't move.

==Creating a Door==

Put simply, to make a door you will be creating an 'entity with model' or 'entity with brush' or some variation thereof.

===Creating a Model Door===

There are several approaches to making a model door; the simplest is to create a door from the entity list; or create a door from the model viewer (good for static unusable prop doors).

'''Entity List''':

*Deselect everything in editor by hitting the Esc button
*Right-click an ortho view and select Create Entity
*Navigate to darkmod/movers/''atdm:door_...'', choose the door you want
*Click Add
*To change its appearance, add a "skin" spawnarg to the door, with the value being the model name of the door you want.

You now have a workable door in your level.

'''Model Viewer''':

* Right click in the orthoview, select ''Create Model'' then <code>darkmod</code> and select a door.
* Note that you can left drag the image in the ''Choose Model'' dialog to rotate it around.
* Click [[Image:Button ok.png]] and you have a static door.
* If you want to make it work (openable, frobbable) then:
** Select the entity inspector,
** Select the top classname line so it highlights
** Select the func_static line in the input box ''below'' the properties window.
** Edit <code>func_static</code> to <code>atdm:mover_door</code>
** Click {{check}} or press {{key-enter}}

Alternatively you can do it the old way:

* Create any temporary brush
* Right click in orthoview and select <code>Create Entity</code> then <code>atdm:mover_door</code>.
* Left lick the model name line in the entity inspector.
* Below it on the ''Entity Inspector'' panel you should now see a button 'Choose Model'
* Left click it, select a door model from the darkmod group.
* Note that you can left drag the image in the ''Choose Model'' dialog to rotate it around.
* The temporary brush was deleted.

In all three instances, you now have a working door with default properties.

Name your door by adding the prop (or modifing it) to name ''My_Door_1''. You can use any name that you feel is appropriate but all doors with handles attached ''must'' have their own specific name. Use the name My_Door_1 for your first attempt as it will be referenced when you get around to attaching handles (see below).

To add a handle and other adjustments, see [[#Customising and Adjusting Door Properties]] below.

===Creating a Textured Brush Door===

'''Tip:''' If unsure of size then you might insert a temporary human AI first to get a sense of height.

==== The simplest brush door: ====

* Drag out a new brush to the size required, eg, a seven foot high door is 84" x 1.1 = about 90 units in Dark Radiant.
* Give it a door texture from the texture browser (or wall texture for a secret door)
* Right click in orthoview and select ''Create Entity'' then <code>atdm:mover_door</code>

You now have a working door but it will rotate around its center. To move the rotation point to where you want the door hinges to be:
* Select the door and press 'v' or the ''Select Vertices'' button to enter vertex editing mode. The door's origin will show up as a small green square in the middle of the brush.
* In top-down orthoview, move the origin from the center to the corner of the brush. This is easiest in drag mode ('q' or the ''Resize'' button), although you can use translate mode ('w' or the ''Translate'' button) by manually selecting the vertex first.

==== Multi-brush doors: ====

More complex multi-brush doors can be created using the [[Clipper]] tool, CSG, etc. - this is not covered in this tutorial. Then assign <code>atdm:mover_door</code> for that whole brush structure. Also you can collect various brushes positioned together in relation to one another as needed, select them all, then assign <code>atdm:mover_door</code> for the group. All the brushes will be children of the <code>atdm:mover_door</code> entity and will rotate and be frobbable, etc. as one unit, as one door. To add further brushes or even model shapes later see the section on [[#Adding handles and other items to doors]].

Name your door by adding the prop (or modifing it) to name My_Door_1. You can use any name that you feel is appropriate but all doors with handles attached must have their own specific name. Use the name My_Door_1 for your first attempt as it will be referenced when you get around to attaching handles (see below). (repeated from above in case you didn't choose to create a model door)

=== Double Doors ===
Double doors are automatically recognised by the code when the doors are spawned. The prerequisite is that both doors are sharing/touching the same visportal. The spawnarg ''auto_setup_double_door'' (which defaults to "1") will take care of setting up the open/lock peer relationship between the two doors. The doors will open/close and lock/unlock along with each other as a result.

What happens behind the scenes: the doors are adding each other to their internal open_peer and lock_peer list, which causes the double doors to perform the same action when frobbed or used.

Note that ''auto_setup_double_door'' will not set the frob_peer relationship, i.e. each door will frob-highlight on its own without highlighting the other door. You'll need to add that spawnarg manually if you want to highlight the entire double door as one.

==Customising and Adjusting Door Properties==

Handles, lockplates, etc. can be added to doors and door properties can be adjusted for rotation, sliding, locking, and more.

Some of the door models have hinge plates and lockboxes that are reskinnable with a good variety of skins.

===Door handles and other door attachments===

'''Summary: just add the property ''bind'' with the door's name to the attachment and position it where you want it on the door. If it's a ''atdm:mover_door_handle'' then it automatically will work as a handle but you can bind virtually anything.'''
You can add handles and other items to doors such that they move correctly with the door whether rotating, sliding, or both and even if the door is not vertical such as a skylight or trapdoor.
Handle models come in two types, ''single handles'' and ''double handles''. A single handle is one sided, this means the handle will be inside the door or outside the door, but not both. A double handle has a lever on the inside of the door and a handle on the outside of the door. Each has benefits.

*'''''Single door handles''''':
Single door handles can be used on a static door, a door that's just for show that no AI's or the player can use. In this case you should just create a door handle from the model viewer, it will be static and have no properties such as scripts. It is for looks only. Note that TDM is trying to establish the expectation that decorative doors that cannot be opened do not have handles (though not all maps follow this).

I will call this ''multiple handles'', see more below.

These can also be useful on brush doors created in the editor that may be very thin or very wide.

*'''''Double door handles''''':
These are models have have a handle inside and outside. The bonus is that they only use one entity. Maps are limited to about 4,000 entities but when you count lights, AI, sound speakers, ect... you can run out of entities quickly on a large map. If you plan on building a large map this is the way to go, even in a small map they have benefits, namely that you only have to attach one handle per door.

Whether you decide to use a single handle or a double handle you must first follow the instructions below and attach one handle first. If you choose a double handle, follow the instructions below and you are done. If you choose a single handle type follow the instructions then also follow the ''multiple handle'' instructions for the second handle.

Both single and double handle types can be found in two places. The model viewer which will create a static model good for show, you can manually add props to make them work OR you can look in the entity browser.
Using a handle from the entity browser saves you a little bit of time as some props are already added, you just need to add the frob_peer names for the doors/handles and the door_handle name to the door.

=== Adding a working model door handle===

Quick summary:
* Create a model or brush handle and make it an ''atdm:mover_door_handle'' entity.
* Position it on your door. Use the opposite side from the door's multicolor X-Y-Z indicator (highlight the door to see it) if it's not obvious which side it goes on.
* '''Bind''' the handle to the door (bind <doorname>)
* It should now be a working handle though may need adjustments of rotation etc. see later.

Important: read preceding section on door handle types and performance issues first.

This works with both a model door and a brush door:

'''Rotation''':
* By default the door handle entity rotates ''anti-clockwise'' (looked at from the front) then springs back. A ''double handle'' model is OK but two singles (see ''Multiple door handles'' below) need more care as only one is the functioning entity and the other is just attached to it. So anti-clockwise is fine for a door with its hinge on the left and the handle on the right - the handle will rotate down then spring back. If you put the functioning door handle on the other side you will have to change the default ''rotate'' property from -45 0 0 to 45 0 0. '''''Therefore it is easier to generally put this handle on the side of the door where the hinge is on the left and the non-functioning attachment handle on the other side.'''''
*If your door only needs one handle, eg, a cupboard door, and from outside its hinge is on the right then you will need to change the ''rotate'' property of the handle as described above.

'''''The functioning handle entity:'''''
* Create an entity door handle (movers folder) or create a brush or model handle and assign it the entity ''atdm:mover_door_handle''.
* Position it where you wish on your door.
* '''Bind''' the handle to the door, by adding the "bind" spawnarg to the handle.

You now have a working door handle with default properties.

*'''Multiple door handles''':
Now that you've got a handle attached to one side of the door it is time to add one to the other side (unless you used a double handle).
* Create the new handle. The single handles come in left and right persuasions. A door needs a left facing handle on one side and a right facing handle on the other, so if you have already added the left handle create a right handle and line it up on the other side of the door.
* Name this handle. I prefer to keep a naming convention for each door and it's respective handles, it makes things alot easier. The door is named '''My_Door_1''', the first handle is named '''My_Handle_1''' so name the second handle '''My_Handle_1_1'''. This will make it stay with the first handle in the entity list. This is important to keep organized. If you name it My_Handle_2 then when you get to another door named My_Door_2 you'll be confused.
* Place and '''bind''' that handle to your door.

You now have two single door handles on either side of the door that rotate together as if they were physically attached.

'''To add a brush to a brush door''':
* Select the new brush ''and'' the brush door all together; ''the entity '''must''' be selected '''last'''.''
* Use {{menu|Edit|Reparent primitives}}. This ensures the parent entity adopts the new item(s).
* If you have trouble selecting them in the orthoview because other brushes, etc. get selected then try in the camera view or as a last resort move them temporarily to an open area (but keep them in the same positions relative to each other.) Use {{key-shift}}+{{LMB}} on new item(s) then {{key-shift}}+{{LMB}} on main entity. Once they are all selected, use the {{menu|Edit|Reparent primitives}}.

'''To add ''model'' static items''': knockers, hinges, static handles etc. to a ''Model Door'':
* Select item
* Right click in orthoview and select ''Create Entity'' then <code>entity func_static</code>
* Position it where you wish on your door.
* To synchronize this with your particular door you need to add the property ''bind'' and the individual door name to the brush entity. To do this...
** Select the model door.
** In the entity inspector, select the ''name'' line
** Select the bottom line in the input box ''below'' the properties window.
** Copy the name
** Deselect the door with {{key-esc}}
** Select the brush entity
** Add a property "bind" to it.
** Change the value of the property by pasting in the door name
** Click {{check}} or press {{key-enter}}

'''To add ''brush'' static items''': knockers, hinges, static handles to a Model Door:
* This method is not ideal but it seems to work OK.
* Select the brush.
* Right click in orthoview and select Create Entity then ''atdm:mover_door_handle''
* Position it where you wish on your door.

To synchronize this with your particular door you need to add the property ''door_handle'' on the door, and give as the value the name of the brush you just created.

This brush turns like a handle. To stop it:

* Adding ''rotate 0 0 0'' or disabling the handle script won't help.
* Add a real working handle (as in the section above ''To add a working model door handle...'' and it must be added LAST.)

If you don't want too see a real working handle added maybe try another tiny brush with the handle function and hide it inside the door?

===Locking Doors===

To lock a door check the ''show inherited properties'' in the entity inspector for a ''atdm:mover_door'' entity and you should see the ''locked'' property. Select it and in the input box below the properties you can change its value:

* 0 = unlocked (default)
* 1 = locked

If locked it will require an entity that is associated with it to be able to act as a key to unlock it.

Currently door handles on locked doors will rotate when frobbed, they will bounce back though and the door will stay locked until unlocked.

===Keys===

Assigning specific keys to specific doors is simple.

* It is recommended that you create an existing key entity. These keys have all required props, they just need to be named.

Alternatively you can create a key from the Model Viewer and want it to be useable
* Make sure it has the properties:
useable 1 [so it can be used by the door]
frobable 1
inv_name <unique name>
inv_category Keys
inv_target player1
inv_icon guis/assets/hud/inventory_icons/<icon name>
inv_stackable 0 or 1 where 1 can be used on all copies of the same key so they show as one entry in the inventory with a total.

Add to the door the property <code>used_by</code> with the name of the key as the value. Multiple keys can open the same door by using several <tt>used_by</tt> spawnargs:

"used_by" "doorkey_1"
"used_by1" "doorkey_2

==== Keys Carried by AI ====

So you have a door and you have a guard AI and you want the guard to be able to open/close/lock the door, but you also want the player to be able to pickpocket the key. Keys can be attached to AI in two ways.

''The Def_Attach Method''. This method is the best one for doors that you expect the AI to operate. It uses spawnargs to spawn the key at game start.

*"def_attach6" "atdm:prop_silverkey" // the entity to spawn - in this case a key.
*"pos_attach6" "belt_back_right" // where the key will spawn on the Ai.
*"name_attach6" "door_key" // this gives 'attach6' arg the name "door_key" and is the name the arg "used_by" will need, eg: "used_by" "door_key"
*"set inv_name on door_key" "Door key" // The name the key get when the play adds it to their inventory.
*"set name on door_key" "door_key" // here it gets a name to be used in the map in general.

For more info on this method, see [[Attaching Props to AI]].

''The Bind Method''. This lacks the animation finesse of def_attach, but does let you see the key in DR. The method is particularly helpful in, say, adding a second key to an AI in the back middle of a belt. The AI cannot use a bound key to open a locked door; the workaround is to fake it with "can_unlock" as discussed further below. Or to use bound keys mainly for items the AI will not attempt to open, such as hatches, duct covers, or chests.

* Load a key entity
* Position where you want it in relation to the AI, and bind it to them (i.e., "bind" "<AIname>")
* Add the spawnarg "bindToJoint" "Hips" (or another location like LeftHips_Dummy; see AI for list)
* Adjust existing spawnargs accordingly (that is, be sure the name and door's/chest's "used_by" match, if you aren't using a prefab chest with key). This is for the benefit of the player after pickpocketing the key; as stated above, the AI itself can't use it for unlocking.

For more info on this method, see [[Attaching_Items]] and [[BindToJoint]].

====Keys Carried by Player====

With a door's key selected in your inventory and the door highlighted, you can...
* unlock it (which will also auto-open if enabled) by either frobbing it or hitting the Use key (typically U or Enter).
* lock (or relock) it via the Use key. Why do this? To avoid pursuit, or to lure guards into a room, and then lock them in (if they don't have a key or specific can_unlock powers).

====Master Key for Testing====

By default, ALL locks can be opened by any key named ''key_master''. Just create a key in your map, name it ''key_master'' and it becomes a master key for use while testing. Add inv_map_start 1 to it so it is in the player inventory at game start. Remember to delete it when your mission is finished.

====Automatically Removing Keys from Player Inventory After Use====
If a fan mission has a lot of keys it can clog up the player inventory. If the key is single-use, it can be useful to automatically remove it from the player inventory after use. Below is a way to do it using a simple setup and a generic script function that can be used for multiple doors.

If you want to avoid scripting, see the [[Doors#Simpler,_No-script_Version|simpler, no-script version]].

=====Generic Version=====

You'll need the following entities, preferably set up near each other in your map:
* The door entity itself
* A trigger_count entity
* An atdm:target_callscriptfunction entity
* some random entity for the target_callscriptfunction to target (explanation below)

The below diagram shows the spawnargs and targeting required for the setup:
[[File:Key remove2.png|left|thumb]]

<div style="clear: both"></div>
The script being called ('openDoor') is defined in fms/<mapname>/maps/<mapname>.script and looks like this:

void openDoor(entity target, entity door, entity callscriptfunction)
{
string keyName = door.getKey("used_by");
entity key = sys.getEntity(keyName);
$player1.replaceInvItem(key, $null_entity);
}

Explanation as follows:

'''For the door:'''
* '''trigger_on_open''' spawnarg: The door is configured to trigger its targets when it opens
* target '''trigger_count''' entity: this is the entity that is triggered when the door is opened
* '''used_by''' spawnarg: This names the key entity required for unlocking the door
* The other spawnargs are just the usual for setting the door as locked and unpickable

'''trigger_count entity:'''
* When triggered, this entity will in turn trigger the script that removes the key from the player inventory.
* '''count''' spawnarg: This is set to 1 because we only want the key removal script called once - the first time the player opens the door.
* this entity targets the atdm:target_callscriptfunction, which contains details of the script to execute

'''atdm:target_callscriptfunction entity:'''
* '''call''' spawnarg: This is the name of the script function to call
* '''foreach''' spawnarg: This version of the script event provides access to the 'activator', or the entity that triggered it (in this case, the door). Using that information we can obtain the key name. See [[A to Z Scripting: Ways of calling a script#target_callscriptfunction|here]] for details.
* '''target any static entity''': For this version of the script event to work, the target_callscriptfunction entity needs to target something. This can be any static entity in the map (i.e. one that won't get removed or anything). I usually just target the nearest entity (e.g. a light or a lamp, or a model). This provides no functionality in the context of this tutorial, it just satisfies the conditions of the script event.

'''The script:'''
* Pretty self-explanatory. The script gets the name of the key entity via the '''used_by''' spawnarg on the door, retrieves the key entity, and then replaces it in the player inventory with a null entity, effectively removing it.
* Any door can use this script as it's generic, although they will need their own trigger_count entities. In theory they could share the same target_callscriptfunction entity, but that might become inconvenient - up to the mapper.

=====Simpler, No-script Version=====
This is similar to above, but is more limited. You need to hard-code the key name as a spawnarg on an atdm:target_itemremove entity as the key name can't be automatically determined like in the above script. This makes it slightly more error-prone as we're naming entities in more than one place, but ideal if you're uncomfortable with scripting.

[[File:Key remove4.png|left|thumb]]
<div style="clear: both"></div>

Explanation as follows:

'''atdm:target_itemremove entity:'''
* '''unique_item ''' spawnarg: The name of the key to remove from the player inventory

===Lockpicks===
''by Baddcog''

There are two lock pick types.
*'''s'''=snake
*'''t'''=triangular

A lock can be set with many pins. Each pin has a click sequence and each needs a designated lockpick type (see above). Keep in mind that the lockpicking in The Darkmod is much more involved than in T2 or T3. The player has to listen to sounds or watch a handle or lockbar to know when a lock is pin is picked.

This means that authors can be very evil and really frustrate the player, in which case their missions will probably not be played. So be nice to the player and don't waste your time. Use simple locks for the most part and save complicated locks for important sections and to build tension. Don't make the player have 20 pins to pick all with different lockpicks. In most cases 1 or 2 pins will suffice and it isn't necessary to use both lockpicks on every lock.
Also try to include a lock lever on lockboxes or chests, door handles will rotate as the pins are being picked. This gives the player visual clues to help with the picking (and essential in noisy environments where you can't hear the clicks.)
IMO this system is a huge leap foward for lockpicking but also has the ability to completely frustrate the player as stated above. Keep this in mind when designing your lockpick systems.

These props go on the door itself, or the lid of a chest, eg,
*'''lock_pins''' 1327
*'''lock_picktype''' stts

The lock_pins property specifies how many pins each lockpicktype has.
The lockpick_type property specifies how many times the player has to switch picks and which pick they have to use. You can see there must always be an equal number of lock_pins and lock_picktypes specified

So looking at the example above we have lockpick_type s(snake), t(triangular), t(triangular), and s(snake). The player will have to use these lockpicks in this order. Once the snake lockpick's pins are open the player can advance to the triangular pick and so forth.
5 is added to every click sequence so 5 is the minimum click pattern even if you set it to 0.
In the example above the lockpins specify in order which pick types have how many pins, so the s pick has 1 + 5 = 6 clicks, the t pick has 8 and so on.
The above is a difficult lock and to avoid annoying the player it is best only used rarely on a special lock like an important big vault door. Ordinary footlockers and common doors can be just 1 or 2 click sequences, eg, lock_pins 2 and lock_picktype t means the player uses one pick and listens for the end of one sequence of 7 clicks.

lockpick_rotate - is placed on the door. It is the amount the visible rotating handle or pin rotates while picking. For a rotating handle or lockbar normally ignore this and leave the default. During lockpicking it oscillates and progresses to the normal full turn of the handle. Example 0 45 0.

lockpick_translate - is placed on the door. It is the amount the visible handle or pin moves in a straight line while picking. Use this if you have eg, a lockbar that you want to move in a straight line and not rotate, eg sliding catch. Example 0 -5 0

By default, doors are pickable. If you don't set up the above lockpick spawnargs then it can't be picked. So there is normally no need to enable lockpicking - just set up the above spawnargs. There is a ''pickable'' spawnarg set to 1 by default. If set to 0 then the door becomes unpickable. But hard to think of an application except in testing or perhaps a special custom situation where it is switched by script perhaps.

===Open, Partially Open, or Closed Door at Game Start===

By default, doors are closed at game start. If you want a door to be already open or partially open then do the following.

'''Note well: Create all doors in their ''closed'' position. Adjust as follows and they will automatically be at the open position when game starts.'''

Already Open Rotating Door:
* Select the door.
* Select the entity inspector
* Check ''show inherited properties''
* Select the ''open'' property
* Edit the value to 1 in the input box below and tick the check button
* The door will now be fully open at game start.

* If you want it only partly open:
* Make sure its ''open'' property is set to 1 as above.
* Right click the entity inspector and select ''add property''
* Click the + sign on the left of the top line where atdm:mover_door is listed to open the folder. (if atdm:mover_door is not listed then the entity was likely changed from eg, func_static. If so, save the map and reload to update the add property list)
* scroll down, select ''start_rotate'' then click {{ok}}
* This adds it to the property list.
* Now select ''start_rotate'' in the property list.
* Edit the bottom line of the input box ''below'' the properties window to the angle you want in the same form as described in the ''Rotate Direction and Open Angle'' section. So for example, to have a door that has a fully open default ''rotate'' value of 0 90 0 to start only half open you would give it a ''start_rotate'' value of 0 45 0.
* In a similar way add the property ''first_frob_open".
* Set it to 1 and a partly open door should then open fully on the first frob.
* Set it to 0 and a partly open door should close on the first frob.

Already Open Sliding Door:
* Select the door.
* Select the entity inspector
* Check ''show inherited properties''
* Select the ''open'' property
* Edit the value to 1 in the input box below and click {{check}} or press {{key-enter}}
* The door will now be fully open at game start.

* If you want it only partly open:
* Right click the entity inspector and select ''add property''
* Make sure its ''open'' property is set to 1
* Click the + sign on the left of the top line where atdm:mover_door is listed to open the folder.
* scroll down, select ''start_position'' then click OK. (if atdm:mover_door is not listed then the entity was likely changed from eg, func_static. If so, save the map and reload to update the add property list)
* This adds it to the property list.
* Now select ''start_position'' in the property list.
* Edit the bottom line of the input box ''below'' the properties window to the position you want in the same form as described in the ''Sliding (Translation) Amount and Direction'' section. So for example, to have a door that has a fully open default ''translate'' value of 0 50 0 to start only half open you would give it a ''start_position'' value of 0 25 0.
* In a similar way add the property ''first_frob_open".
* Set it to 1 and a partly open door should then open fully on the first frob.
* Set it to 0 and a partly open door should close on the first frob.

===Rotation Centre, Pivot, Hinge point===

The centre of rotation of a door is at the origin point of its entity and the door rotates with reference to the orientation of that origin point, not the world map. See ''Rotate Direction...'' for more about that. This section only deals with the ''position'' of the rotation centre in the door.

Model Door Centre of Rotation:<br>
The centre of rotation of a model door cannot be changed within Dark Radiant. Because a model door rotates around the centre 'spine' of its back edge this will cause clipping (penetration into solid) as in this example (where the door is set to open to 89 degrees for clarity):<BR>[[Image:modelClipping.jpg]]<BR> So care is needed with placement. You will not normally position a door right next to a wall as in the example but against a shallow frame so clipping will barely be noticeable but either way it can be fixed. You can correct it by adding a translation (see ''Sliding (Translation) Directions'') value of half the door width in the direction of the door handle. This will gently move the door out as it rotates to clear any solid on that side as in this diagram:<br>
[[Image:DoorClip.jpg]]<br>
Half a door width will typically be about 2. Any 'attachments' such as door handles will still synchronize with the door movement whether the door is rotating, sliding, or both.

Brush Door Centre of Rotation:<br>
The centre of rotation of a brush door ''can'' be changed. The default origin point of a brush is at its centre. Therefore a default rotating brush door will rotate around its centre when you first create it. So, mappers will commonly need to move that rotation point to a corner or even to some other offset position for example, for an openable window using the door function.

Put simply, to move the rotation point of a brush door you need to move the entity origin relative to the brush(es.)

Moving the entity origin (centre of rotation) relative to a brush door:

* Select the brush door
* Select ''Vertices mode'' (default shortcut key is {{key|name=V}} or button on top toolbar 'Select Vertices')
* Drag the door's entity origin to the point where you want the door to rotate. This should be on the corner on the leading edge side (the side to where the door is opening.) to avoid clipping as in this diagram....
[[Image:getCorner.jpg]]
* You should now find that door rotates around that point.

===Rotate Direction and Open Angle===

By default, rotating doors open anti-clockwise (viewed from above) by 90 degrees from the start orientation. If you want to change this edit the ''rotate'' property in the entity inspector. Don't confuse this ''rotate'' property with the ''rotation'' property. In the entity inspector remember that to see the inherited rotate property you must check the box 'Show inherited properties'.

The three values shown in the rotate property are degrees from the closed position around Y Z X (absolute map axes Front, Top, Side views in DR's ortho view.)

* Positive Y = Open clockwise (Dark Radiant grid front view, looking north)
* Negative Y = Open anti-clockwise (Dark Radiant grid front view, looking north)

* Positive Z = Open anti-clockwise (Dark Radiant grid top view, looking down)
* Negative Z = Open clockwise (Dark Radiant grid top view, looking down)

* Positive X = Open anti-clockwise (Dark Radiant grid side view, looking west)
* Negative X = Open clockwise (Dark Radiant grid side view, looking west)

There is a problem when you come to rotations that are not around the main Y Z X axes of the map, for instance a drawbridge that lowers down to the south east. You might think you can combine Y Z X values to get the result you want - and this can be done (for south east use 45 45 90) but it is a bit of a kludge and the drawbridge twists eccentrically as it lowers (though it arrives correctly!)

The values are in the range -179 to +180. Positive values give an anti-clockwise opening rotation (looking down from above) and negative values give a clockwise opening rotation. The value 180 is unique in that it continues in an anti-clockwise rotation when closing rather than returning clockwise so might be used if you can think of some object that might need such a motion when frobbed!

Edit the rotate value by selecting it and using the input box at the bottom and clicking the check(tick) button. That will change the angle the door will open to. Note that the line with the original default of 0 90 0 will still be there but your new entry will be added on a separate line and that is the one that will work in the game. CAUTION: when adjusting later make sure you have your new line selected and not the original! If you do it will appear to change but your first setting will remain unaltered.

Examples:
* 0 90 0 = Opens anti-clockwise round the entity's 'vertical' to 90 degrees - typical default vertical door.
* 0 0 90 = Lowers a drawbridge from the entity 'vertical' to horizontal.
* 0 0 -45 = Opens clockwise by 45 degrees viewed from the east side. This might suit a skylight in a sloping roof.

'rotate' cannot be combined with translate motions (see [[#Sliding (Translation) Amount and Direction]]) in one door; you need to bind one door to another and link they by targetting one to the other. By that means you can produce exotic and useful motions. A door opening against an upward-sloping floor can thus have a ''lifting hinge'' and raise up slightly to clear the floor; a door can rotate towards you and slide back to one side very effectively.

===Sliding (Translation) Amount and Direction===

By default a Dark Mod door will rotate open. For most sliding doors you want to stop them rotating as well as make them slide. You cannot delete (remove) the ''rotate'' property - you have to set the ''rotate'' property to 0 0 0 to stop a door rotating (see ''Rotate Direction and Open Angle''.)

Now edit the ''translate'' property value by selecting it (remember to have inherited properties box checked) and using the input box at the bottom and clicking the check(tick) button. That will change the distance the door will slide to. Note that the line with the original default of 0 0 0 will still be there but your new entry will be added on a separate line and that is the one that will work in the game. CAUTION: when adjusting later make sure you have your new line selected and not the original! If you do it will appear to change but your first setting will remain unaltered.

Typically (but not always) you will want your sliding door to slide the width of the door. The three values in the translate property by default are 0 0 0 and are X Y Z ''absolute map'' values (irrespective of door orientation) where:

* Positive X = Slide East (Right side of Dark Radiant grid in top view)
* Negative X = Slide West (Left side of Dark Radiant grid in top view)
* Positive Y = Slide North (top of Dark Radiant grid in top view)
* Negative Y = Slide South (bottom of Dark Radiant grid in top view)
* Positive Z = Slide Up (Top of Dark Radiant grid in side views)
* Negative Z = Slide Down (Bottom of Dark Radiant grid in side views)

So for a 50 unit wide door you want to slide fully to the east you would use 50 0 0 for the translate property values. A 100 unit portcullis sliding vertically up would need 0 0 100 to be fully raised.

=== Doors Collision/Push Behaviour ===
Doors push all entities by default, except for the player. Doors will also stop moving when anything blocks their movement. However, this default behaviour can be changed by setting appropriate spawnargs:

Set '''push_player''' to '''1''' to let the player be pushed by this door:
"push_player" "1" // Push the player too (default is off)

By default '''stop_when_blocked''' is set to 1 and if a door is blocked by an entity then even if the entity is removed afterwards, the door stays where it is. The next frob will close the door.

Set '''stop_when_blocked''' to '''0''' to prevent the door from ending the opening sequence when anything blocks its way. It will still pause - but continue to open if the block is removed.
"stop_when_blocked" "0" // door keeps moving after being blocked (default is off)
With this setting, doors will still stop at blocking entities (the player, for instance), but will continue to move when the entity moves out of the way.

There is another spawnarg which stops a door pushing a moveable. Apply this to the ''moveable'', not the door...

"notPushable" "1"

===Door Sounds===

There are multiple ways to put sounds on doors.

''snd_open'' <br>
Sound is triggered as the door begins to open.

''snd_opened'' <br>
Sound is triggered when the door finishes opening. Defaults to "nosound".

''snd_move''<br>
The sound plays while the door moves. Defaults to "nosound".

''snd_close'' <br>
Sound is triggered as the door finishes closing.

The following sounds should be left on the default sound in most cases so players clearly know what is going on:

''snd_locked''<br>
The sound played when a player or an AI tries to open a locked door.

''snd_unlock string''<br>
The sound played when a door is unlocked.

You can silence any of these sounds by setting the following properties as shown:

''snd_open nosound''<br>
''snd_close nosound''

Don't just use a dash - as it seems to cause a sound of its own.

===Sound Propagation through Doors and Doorways===

''This information will change significantly with the release of 2.0. See'' [[Controlling Sound Loss Across Portals]]

The sound volume reduction to the player (ie, the sound the player hears) is fixed and constant in a cvar which adds a distance factor to the original sound. It is recommended that you do not change that because it will affect other FMs. Currently there is no way to change the way that sound to the player is reduced through doors and doorways.

Sound propagation to AI, eg, impact sounds or guard yells is treated separately:

Sound propagation to AI relies on visportals. For details study [[Sound Propagation: Part 1]] and [[Sound Propagation: Part 2]] as well as [[Visportals]] This tutorial will just cover the relevant sound and sound propagation ''properties'' of doors. If you set the ''show inherited properties'' box in the entity inspector you can see them as described here.

Remember, the following have no effect on what the player hears through a door or doorway.

''loss_open''<br>
Drop in sound volume in dB propagated to AI (not player) when going through an open door. (default 1dB)

''loss_closed''<br>
Drop in sound volume in dB propagated to AI (not player) when going through a closed door. (default 15dB) You would want to set this very high to block all sound with a thick door but very low for a barred gate for example.

''loss_double_open''<br>
Drop in sound volume in dB propagated to AI (not player) when going through double doors when only one is open. (default 1dB)

There are also various sound properties for lockpicking:<br>
''snd_lockpick_pin_1 through 14'' and ''snd_lockpick_pin_success''

===Allowing the Player to Interrupt Door Motion===

The door property ''interruptable'' determines whether a door can be stopped by frobbing while it is opening or closing. It is enabled (i.e., set to 1) by default. Then the player, by frobbing to start the normal opening, then frobbing again to interrupt, can open a door to any position, e.g., slightly ajar to peek through. Another frob will begin closing, and so on with any additional frobs to stop/reverse-direction.

Be aware that an rotating-style door, when left ajar, will subsequently open or close more slowly than normal in an angular-velocity sense. It instead takes the same time as a full (uninterrupted) opening or closing would take in seconds, as given by ''move_time'' discussed next.

===Speed of Door Opening and Closing===

Rotating Door Speed:<br>
The time a rotating door takes to open or close is set in the ''move_time'' property, no matter what its maximum open angle may be. So with rotation set at, say, 150 degrees the door just opens faster than at, say, 80 degrees. To change this value, make sure the door is selected then...

* Right click the entity inspector and check ''show inherited properties''
* Scroll down, select ''move_time''
* Edit the second line of the input box ''below'' the properties window to the time you want.
* The time is in seconds and decimal fractions can be used. The default is currently 1.75 seconds.

Sliding Door Speed:<br>
The speed of a sliding door is set in the ''translate_speed'' property. To add this, make sure the door is selected then...

* Right click the entity inspector and check ''show inherited properties''
* Scroll down, select ''translate_speed''
* Edit the second line of the input box ''below'' the properties window to the speed you want.
* The speed is in Dark Radiant grid units per second.
* The default is 0 and if set to this then the door slides open in one second whatever the distance, great or small.
* CAUTION: It is assumed ''translate'' has been changed from its default value of 0 0 0. If not, a non-zero ''translate_speed'' may cause problems.

===Visportals and Doors===

A visportal face surrounded by solid at its edges and in contact with a door is closed when the door is closed and enabled when the door is open. In most cases you will place a visportal in contact with a working door unless you can see through the door (such as a true glass door or barred gate*.) For full details see [[Visportals]].

''*As of 2.0 it is possible to make visportals that remain transparent when closed for gates and windows. See'' [[Controlling Sound Loss Across Portals]]

==Auto-Closing/Opening Doors==
Doors that automatically close after being open for some time are easy to setup: Each frobmover entity supports these spawnargs:

;"auto_close_time":Set this to something >= 0 to let the mover automatically close (again) after this time when being fully opened (measured in seconds). Defaults to -1, which means 'do not autoclose'. The event is also activated when the mover starts at the open position at map start.
;"auto_open_time":"Set this to something >= 0 to let the mover automatically open (again) after this time when being fully closed (measured in seconds). Defaults to -1, which means 'do not autoopen'. The event is also activated when the mover starts at the closed position at map start.

<div class="toccolours mw-collapsible mw-collapsed">
Before auto_close_time and the AI Door Management spawnargs next were provided, a more laborious method was used to auto-close doors as if AI were closing doors behind them. Hit "Expand" to review it.
<div class="mw-collapsible-content">I have one door that I particularly want the AI to close as there is a bit of frame lag inside if not. So I set this up and it works good as an auto-closing door - not as good as a true AI closing door as it will auto close when the player goes through as well but it does look very effective to see AI going through and closing the door behind them. Not tested exhaustively so I don't know if there could be any downside. Here's what to do....

First a quick summary to make it more clear:

'''''A trigger_relay is used both as a relay AND carries a stim. We put the trigger_relay with its stim in the path of the open door. The door has a response property. When it opens and contacts the stim its response is to send a signal back to the relay. The relay pauses then closes the door...'''''

* First, optionally give your door a suitable name like autodoor1, whatever.
* Copy that name to the clipboard.

Next we need a relay with a delay:

* Create entity > darkmod > trigger_relay

* Place it roughly at the position the door will be at when open and to be on the safe side 3/4th of the way to the far end of the door (not the hinge end) to give max distance from the close door.

* Add the property 'target' and paste in the door name you just copied.

* Give the relay itself a name, eg, autoDoor_relay_1, and copy that name to the clipboard, you'll need that too in a bit.

* Add the property delay and the value 3 - this is the delay in seconds before the door will close; 3 seems about right but 2 might be worth a try because to that 3 is added a random value between 0 to 0.5 seconds from the Time Interval we entered for the stim firings.

* Add the property 'wait' and the value 3. This is the time before it can work again in seconds. If you set it too low then in theory the door might trigger again but in this situation I don't think it's possible. Too long, eg, one minute, and it won't work if the AI goes back through the door before then. If this value is -1 then the whole thing will only work ONCE so might be used for an AI who goes through once, closes it behind him, but you don't want it to be an autodoor thereafter.

That's the relay, now we add a stim to it:

* Still with the trigger relay selected, go to {{menu|Entity|Stim/Response}}

* Custom stim tab.

* Click Add stim type, select the new custom stim type you just made at the bottom of the list and type in eg, autoDoorStim at top right in the input box.

* Click the stim tab and the little drop down arrow against the 'type' selector at bottom left and you should see your new custom stim name. Select it.

* Select the new autoDoorStim in the list and on the right you need only type in the radius box 15.0 There is quite a lot of room for error. I had it working on 10 and also on 25. The value should be less than the distance to the closed door else it will trigger open! But no so small that the door might not reach it.

* Select the check box for Time Interval and enter 500 (millisecs.) This is so it doesn't keep firing more frequently than is necessary. This stim will be firing all through your mission whether the door is used or not so if you had dozens of these then maybe it would affect performance. Too big a number and there may be a long delay before the door shuts - but it will be random depending on the next time the stim happens to fire. We'll control the delay we want more precisely later.

* Click {{ok}} to confirm it.

That's the stim set up, now for the response to it which is put on the door....

* Select the doorm, then use {{menu|Entity|Stim/response}} and select the response tab.

* Click the little drop down arrow against the 'type' selector at bottom left and you should see your new custom stim name. Select it.

* Right click in the big ''Response Effects'' box on the bottom right of the panel.

* Add New Effect and you should get a default 'Activate Response' response added to the list. Double click it.

* In the Effect selector at the stop select 'Trigger'

* in the Target box, paste in the name of the relay you copied or you can select it from the list at the little arrow.

* Leave the Activator box empty.

* Click {{apply}} and then {{ok}} on the main S & R panel bottom right.

It should now work. No need to wait for an AI, just frob the door and watch it close itself. If not, check the position of the stim brush is close to where the door stops when open.</div>
</div>

==AI Door management==

By default AI will open doors and close them behind them. Here are some spawnargs '''on the door''' the mapper can use to modify that behaviour:

;"ai_should_not_handle" :If set to 1, AI will not attempt to handle it and add it to the forbidden areas (so that it doesn't try to path through). They might still walk through the door when it is open though. Useful if you have some special use door that you don't want the AI to operate.

;"ai_should_not_close" :If set to 1, AI will not close the door behind them unless it obstructs them.

;"canRemainOpen" :If set to 1, it's the same as "ai_should_not_close, with the added behavior that this is ignored if the door needs to be relocked, or the door is marked "shouldBeClosed". '''(This spawnarg is available starting in TDM 2.02.)'''

Spawnargs '''on the AI''' that the mapper can use:

;"canCloseDoors" :Added in 2.12. Defaults to 1. If set to 0, the AI will not close doors after passing through them.

To get AI to unlock/relock specific doors there are two methods:

1. Provide the AI with the key, as detailed in the def_attach method in [[#Keys_carried_by_AI]] above.

2. Add the following spawnarg/value to the AI:

;"can_unlock" ''<doorname>''

For additional doors on the same AI use ''can_unlock1 doorname', `can_unlock2 doorname' etc. '''Do NOT use can_unlock_1.'''

If both (1) and (2) are used, then the AI can still go through the door after the player pickpockets the key. Otherwise, unless someone else opens the door for the AI, a typical sequence is that the AI checks their pockets for the missing key, stalls a bit at the locked door, and then (with now-better pathing algorithms) the AI uses an alternate route to the next path_corner, or "mentally" skips ahead in the route to next reachable node and goes there.

===Door Handling Positions===

It is also possible to set custom door handling positions for the AI. This is especially useful when the standard routine that lets the AI choose their standing positions while opening and closing the door fails, leaving them standing still, or circling around in front of the door helplessly.

Place a movers > ''atdm:door_handling_position'' entity where you want the AI to stand while opening/closing the door from this side.

On the door, you need to set the spawnarg "door_handle_position" "name_of_door_handling_position". You can also place a ''door_handling_position'' on each side of the door, and the AI will automatically choose the right one. In this case, you need to set spawnargs with "door_handle_position_1" etc., and the corresponding names of the ''door_handling_position'' entities on the door.

The ''door_handling_position'' entities can also carry spawnargs that define the behaviour of the AI, which are useful for example for doors that can only be opened or locked from one side:

'''"ai_no_open"''' If set to "1", the AI will not try to open the door from this side (but will still walk through when the door is already open).

'''"ai_no_close"''' If set to "1", the AI will not attempt to close the door from this side.

'''"ai_no_unlock"''' If set "1", the AI will not be able to unlock the door from this side, but still use it when it is not locked.

'''"ai_no_lock"''' If this is set "1", the AI will not lock the door from this side.

===Door Controllers===

'''Available in TDM 2.02+'''

You can design a door so it's operated by buttons or levers or switches (aka ''controllers'').

A controller is simply an entity that targets the door. Typical examples of entities that can be used are:

* Buttons: atdm:mover_button
* Levers: atdm:switch_rotate_lever
* Switch: atdm:mover_lever
* Lock: atdm:froblock. (See also next section)

1. Set up the door in the normal manner. It can be a rotating door, a sliding door, a locked door, etc.

2. Turn off the "frobable" spawnarg on the door. ("frobable" "0")

3. Create a controller entity on each side of the door. If you're setting up a locked door using atdm:froblock, there's no need to put any locking information on the controllers. When the game starts, it will transfer any locking information from the door to the controllers.

4. Give each controller the door as a target.

Both the player and any AI that wants to use the door will use the controllers to operate it. Any key, "can_unlock", or lockpick settings you would normally use at the door are now used at the controllers.

Controllers and ''door_handling_position'' entities can be used on the same door, but in that situation the ''door_handling_position'' entities don't define where the AI stands to operate the door. They simply provide the "ai_no_*" spawnargs that define AI behavior on each side of the door.

If you wish, you could provide a controller on only one side of the door instead of both sides. Note that, since the door is not frobable, the player won't be able to operate the door from the non-controller side.

====More about Using a Separate "Froblock" Lock Plate====
''by Geep, 2021-22''

Froblock, just discussed as a controller method, actually predated the controller concept in TDM. Here we recap that earlier context, with an alternative treatment of highlighting, and thoughts on texturing and usage.

Suppose you want to have a lock plate (typically mounted on a door frame or wall) that opens a nearby door, where the door and lock plate highlight separately. A traditional way is to adapt the ''froblock'' method described under the "Making your own" section of [[Containers, Chests, etc.]]

Basically, your door is the "chest lid" (of class atdm:mover_door) and your lock is the "chest body" (of class atdm:froblock). Set the properties as described in the wiki. There is a stock texture (darkmod/door/keyhole_metal_001) you can use to decorate a surface of your lock plate, or a patch on it. This method is probably most apt for small hatches and grates designed for the player alone, and with no handles, or non-turning handles attached with "bind".

===AI and 'non-frobable' Doors===
Be aware that the 'frobable' spawnarg only applies to the player, not AI. If you set a door to be non-frobable (i.e. 'frobable' '0'), AI can still operate it by interacting directly with it, even if it has a controller. For example they will do this if:

* they are fleeing or chasing the player
* the door has a controller but the AI can't reach it (for example the controller is on the other side of the door)

The best way to mitigate this is to use Door Handling Position entities (see above) with the 'ai_no_open' spawnarg set on them.

===AI locking doors behind them===

If one AI is involved (no one else is in the queue), he'll lock it behind him if he had to unlock it in the first place.

Prior to TDM 1.08, if more than one AI is using the door at the same time (there's a queue), the first AI unlocks the door, and the last AI through will only lock it if it's marked "should_always_be_locked" AND they have a "can_unlock" for that door or they have a key for that door. The last AI to use the door doesn't know that the first AI found it locked, because that info is kept per AI, and not per door.

Starting in TDM 1.08, if the first AI in a door queue found the door locked, that information is remembered by the door and the last AI through uses it to relock the door, as long as they have a "can_unlock" for that door or they have a key for that door.

In the rare case where a door is set up to use door-handling position entities (necessary for AI to use sliding doors), either or both of those entities can have the "ai_no_lock" spawnarg, which means AI aren't allowed to lock the door from that side.

==Initially Blocking a Door - Partially or Fully==
''by Geep 2021''

Suppose you have a door that you want to start out either as unopenable, or able to open just a crack, then later, after something happens, be fully openable and operational. One method known to work:

* Create a moveable object that the opening door runs into and tries to push.
* Arrange that the far side of the moveable object is jammed against some immovable worldspawn.

Here's two specific examples that use a wooden plank moveable:

* In "Perilous Refuge", a plank blocks the door leading out of the player's starting location, until the player carries it away.
* At the end of "Away0" (WIP 2021), the player tries to open a door. But if preconditions aren't met, the occupant seems to let the door open only a crack and complains. Blockage is done by an unseen plank resting on the floor hitting a knob of worldspawn. Preconditions met causes a "$plank.remove()" script call.

Other methods that you might think would work but don’t:

* Block with a func_static object, or an unjammed moveable with "notpushable 1" set. In both cases, the door travels through the object.
* In advance, "grab" an unjammed moveable to make it appear "solid" to the physics engine. (This was tested by having the player manipulate it; if it had worked, a “grabber” script call might suffice.)
* Dynamically change the door’s "rotate" limit from script using "setSpawnArg"; this function would only work before you spawn the door, not afterwards.

(Others possibilities not yet tested:

* Change "rotate" using the "setKey" script function; for some spawnargs this works even after spawn.
* Create a moveable and bind it to the world entity.
* If you are mainly interested in initially blocking an AI from using a door: it's possible that the AI re-reads the spawnargs for what doors it's allowed to open. Try adding a frob Response to the key (Entity -> Stim/Response... -> Response) with an effect that sets the “can_unlock" spawnarg on that AI to "-".)

==Controlling a Door by Scripting==
''by Geep 2021''
===If Unlocked===

Simply use, for example with a door named ''door1'':

$door1.Open();
...
$door1.Close();

Alternatively, toggle it open or closed with:

$door1.frob();

If the door has "interruptable 1" (which is the default with atdm:mover_door), you can also frob() it twice to leave it ajar. Interpose and adjust a sys.wait(...) to tune it.
===If Locked===

You need to unlock it first. Changing the door's "locked" spawnarg value won't work. Instead you will use:

$door1.Unlock();

But there are complications. By default, the door has spawnarg "open_on_unlock 1". So, assuming you didn't change that, you'd think unlocking the door would open it. But this spawnarg will be ignored if the gamer has global menu option "Open Doors on Unlock" set to Off. Assuming you want to reliably have the door open, do this:

$door1.Unlock(); // MAYBE will open door too.
sys.wait(3); // If so, wait for door to fully open. Value may need adjusting based on door's speed
$door1.Open(); // Otherwise, open it now.

The wait is added, because otherwise, the opening begun by Unlock may be stopped by Open with the door only partially open. (Probably an alternative to using sys.wait here is to zero the door's "interruptable" spawnarg.)

==Doors as Triggers==

''by Ishtvan & greebo''

Doors (or any binary frob mover, buttons, levers, etc) now have the option to [[Triggers|trigger]] their target on closing or opening. (For definition purposes, a button is defined as "closed" in the state when it starts out and "open" in the state you press it down to. I know that's a little non-intuitive, but it came from deriving from doors).

New spawnargs on frob movers:
;"trigger_on_open" :If set to 1, this binary mover will trigger its targets when it starts out completely closed and is opened.
;"trigger_when_opened":If set to 1, this binary mover will trigger its targets when it is completely opened. Code defaults to 0.
;"trigger_on_close":If set to 1, this binary mover will trigger its targets when it completely closes after being open.

== Suspicious Doors ==

If you give a door the spawnarg '''"shouldBeClosed" "1"''', then AI will treat it as suspicious if they find the door open.

Doors with that spawnarg should work like this:

- an AI opening the door knows he's not to become suspicious if he opened the door

- nearby AI alerted by the open door will also not react if they can see the door, and can see the AI that opened it

- AI who come upon the open door later probably won't be able to see the AI that opened it, so they'll treat it as suspicious

- if the AI who opened the door comes upon the door later, and it's still open, and no one's touched it since he opened it, he'll see his name on the door and won't become suspicious. "Oh, crap. I forgot to close it earlier."

- If an AI comes upon an open door that should be closed, he should close it whether he becomes suspicious or not.

'''Post TDM 2.00:'''
- AI turn to look at a door they see opening. The player can crack open a suspicious door to peek out w/o grabbing the attention of a nearby AI. After 5s, the AI will notice the cracked open door. Non-suspicious doors can be cracked open indefinitely w/o nearby AI noticing.

==Slanted or Tilted Doors==
Slanted or tilted doors can be made as follows:

1) Place your door, preferrably one of the prefab doors, which have a model door and model handle and all the rotation spawnargs pre-set.

2) rotate and place the door+handle model into place you want it to be. Now, if you use the door in the game, the door will rotate around the world z-axis, and not the door model z-axis (which is rotated).

3) to get the door to rotate around the door model z-axis, you must place a model (any model will do, and it can be placed anywhere in the map). Rotate the new model into the same orientation your door model was rotated, i.e. if you door is rotated 45 degrees around the x-axis, do the same rotation on the new model.

4) bind the doors on the new model. This makes the doors start rotating along the new model origin (which is rotated the same way as the doors).

5) working slanted door.

Do note, that all the rotated objects need to be models (suspicion, not tested). You can export DR built stuff into a model using the DR ase exporter script. For custom doors, remember that the exporter places the model origin at the map origin if you do not choose the "place origin in the middle of the object" option.

Also note that the AI probably cannot use slanted doors and might get stuck (suspicion, not tested).

There is a link to a test map here:
http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/?p=395486

==Skins: A Wide Variety of Door Textures==

This is to remind you that as with many Dark Mod models, there is a wide range of extras skins (textures) available for door models. There are now several basic door entities of different sizes so choose your size first. Then enter the spawnarg: skin with any temporary value. Now select it and click the skin button at the bottom of Dark Radiant's Entity Inspector and you will find a large of range of skin textures from which to select to give you a choice of appearances for your door.

==Extra Notes==

''func_darkmod_door'' is no longer used (just in case you come across it in the Dark Mod forums or wiki.) '''<code>atdm:mover_door</code>''' is the entity to use.

{{tutorial-editing}}

Doors

2025-11-06T20:23:32Z

Frost Salamander: /* Generic Version */

{{todo}}
''Written by Fidcal'' ''edit Baddcog''

==Quick Summary==

Quick way to get an unlocked door in your map:

* Insert one of the prefab doors complete with handles and select its skin property and click the button to change its skin appearance to whatever you want. Set any other properties you need.

Alternatively,

* Create a door from the entity list
* Use the "skin" spawnarg on the door to change its appearance.
* Create a handle from the entity list
* Add the ''door_handle'' property to the door and give it the name of the handle
* To the door handle add the value frob_peer and use the name of the door.
* To open clockwise, change the ''rotate'' property from <code>0 90 0</code> to <code>0 -90 0</code>

==Introduction==

This tutorial explains how to put doors into your map using Dark Radiant, as well as adjust them and their properties.

The rest of this tutorial assumes that you have a basic understanding of using DarkRadiant. If you haven't done so, please go read the [[Dark Radiant Must Know Basic Intro]] article first.

Additionally:

* Up, down, right, and left in Dark Radiant's ''top'' orthoview are regarded here as the standard map directions of North, South, East, and West where useful for clarity.
* Where the term ''brush'' is used with a door it mostly also applies to a door made up of a group of brushes and/or patches.
* Where the term ''door'' is used it often will also apply to any object you wish to rotate when frobbed, for instance an openable window, box lid, or even more exotic objects that the imaginative mapper might conceive like a signal, engine part, toy, or whatever. So long as it needs to turn or slide just a fixed amount when frobbed then return when frobbed again then the following applies.

==Door types==

All tangible objects in Dark Mod are ''entities'', having either a pre-made model shape or else brush/patch(es). So there are two ways to create a door in Dark Radiant: as a model door or a textured brush door (or a hybrid of the two).

Models are ready made door objects but cannot within Dark Radiant (at the time of writing) be resized, rescaled, cropped or clipped whereas brushes are very flexible in that respect and can be worked into custom shapes for your map, including secret doors that blend into walls and other surfaces.

Most of the current door models are found in two places along with the door handles.
*Model Viewer: doors created from here will be static in the world and have no props other than material type.
You can add any props to them to make them working doors. If nothing else it is a good place to view the different size and skin options for the doors.
*Entity List: most of the door models can be found here. These doors have properties already assigned so they are ready to be used. Only one base door of each type is listed, create the size/hinge count door you want (2 hinge doors have a 'no hinge' skin). You can choose a skin for the door once it has been created in the editor with the "skin" spawnarg (use the model name of the door you want, taken from the model list, as its value). This is the easiest way to create a door. The same goes for door handles.

Remember also that door functions may be applied to objects other than doors, such as openable windows, drawbridges, gates, etc. In fact, anything that needs a partial rotation or slide when frobbed then return when frobbed again, such as a signal device. Lockboxes and chests use similar properties.

You can create one door/handle set and copy/paste it, but you need to take great care that all the name props are changed to match in each clone. Otherwise you get handles that fly off when a distant door moves, and handles that don't move.

==Creating a Door==

Put simply, to make a door you will be creating an 'entity with model' or 'entity with brush' or some variation thereof.

===Creating a Model Door===

There are several approaches to making a model door; the simplest is to create a door from the entity list; or create a door from the model viewer (good for static unusable prop doors).

'''Entity List''':

*Deselect everything in editor by hitting the Esc button
*Right-click an ortho view and select Create Entity
*Navigate to darkmod/movers/''atdm:door_...'', choose the door you want
*Click Add
*To change its appearance, add a "skin" spawnarg to the door, with the value being the model name of the door you want.

You now have a workable door in your level.

'''Model Viewer''':

* Right click in the orthoview, select ''Create Model'' then <code>darkmod</code> and select a door.
* Note that you can left drag the image in the ''Choose Model'' dialog to rotate it around.
* Click [[Image:Button ok.png]] and you have a static door.
* If you want to make it work (openable, frobbable) then:
** Select the entity inspector,
** Select the top classname line so it highlights
** Select the func_static line in the input box ''below'' the properties window.
** Edit <code>func_static</code> to <code>atdm:mover_door</code>
** Click {{check}} or press {{key-enter}}

Alternatively you can do it the old way:

* Create any temporary brush
* Right click in orthoview and select <code>Create Entity</code> then <code>atdm:mover_door</code>.
* Left lick the model name line in the entity inspector.
* Below it on the ''Entity Inspector'' panel you should now see a button 'Choose Model'
* Left click it, select a door model from the darkmod group.
* Note that you can left drag the image in the ''Choose Model'' dialog to rotate it around.
* The temporary brush was deleted.

In all three instances, you now have a working door with default properties.

Name your door by adding the prop (or modifing it) to name ''My_Door_1''. You can use any name that you feel is appropriate but all doors with handles attached ''must'' have their own specific name. Use the name My_Door_1 for your first attempt as it will be referenced when you get around to attaching handles (see below).

To add a handle and other adjustments, see [[#Customising and Adjusting Door Properties]] below.

===Creating a Textured Brush Door===

'''Tip:''' If unsure of size then you might insert a temporary human AI first to get a sense of height.

==== The simplest brush door: ====

* Drag out a new brush to the size required, eg, a seven foot high door is 84" x 1.1 = about 90 units in Dark Radiant.
* Give it a door texture from the texture browser (or wall texture for a secret door)
* Right click in orthoview and select ''Create Entity'' then <code>atdm:mover_door</code>

You now have a working door but it will rotate around its center. To move the rotation point to where you want the door hinges to be:
* Select the door and press 'v' or the ''Select Vertices'' button to enter vertex editing mode. The door's origin will show up as a small green square in the middle of the brush.
* In top-down orthoview, move the origin from the center to the corner of the brush. This is easiest in drag mode ('q' or the ''Resize'' button), although you can use translate mode ('w' or the ''Translate'' button) by manually selecting the vertex first.

==== Multi-brush doors: ====

More complex multi-brush doors can be created using the [[Clipper]] tool, CSG, etc. - this is not covered in this tutorial. Then assign <code>atdm:mover_door</code> for that whole brush structure. Also you can collect various brushes positioned together in relation to one another as needed, select them all, then assign <code>atdm:mover_door</code> for the group. All the brushes will be children of the <code>atdm:mover_door</code> entity and will rotate and be frobbable, etc. as one unit, as one door. To add further brushes or even model shapes later see the section on [[#Adding handles and other items to doors]].

Name your door by adding the prop (or modifing it) to name My_Door_1. You can use any name that you feel is appropriate but all doors with handles attached must have their own specific name. Use the name My_Door_1 for your first attempt as it will be referenced when you get around to attaching handles (see below). (repeated from above in case you didn't choose to create a model door)

=== Double Doors ===
Double doors are automatically recognised by the code when the doors are spawned. The prerequisite is that both doors are sharing/touching the same visportal. The spawnarg ''auto_setup_double_door'' (which defaults to "1") will take care of setting up the open/lock peer relationship between the two doors. The doors will open/close and lock/unlock along with each other as a result.

What happens behind the scenes: the doors are adding each other to their internal open_peer and lock_peer list, which causes the double doors to perform the same action when frobbed or used.

Note that ''auto_setup_double_door'' will not set the frob_peer relationship, i.e. each door will frob-highlight on its own without highlighting the other door. You'll need to add that spawnarg manually if you want to highlight the entire double door as one.

==Customising and Adjusting Door Properties==

Handles, lockplates, etc. can be added to doors and door properties can be adjusted for rotation, sliding, locking, and more.

Some of the door models have hinge plates and lockboxes that are reskinnable with a good variety of skins.

===Door handles and other door attachments===

'''Summary: just add the property ''bind'' with the door's name to the attachment and position it where you want it on the door. If it's a ''atdm:mover_door_handle'' then it automatically will work as a handle but you can bind virtually anything.'''
You can add handles and other items to doors such that they move correctly with the door whether rotating, sliding, or both and even if the door is not vertical such as a skylight or trapdoor.
Handle models come in two types, ''single handles'' and ''double handles''. A single handle is one sided, this means the handle will be inside the door or outside the door, but not both. A double handle has a lever on the inside of the door and a handle on the outside of the door. Each has benefits.

*'''''Single door handles''''':
Single door handles can be used on a static door, a door that's just for show that no AI's or the player can use. In this case you should just create a door handle from the model viewer, it will be static and have no properties such as scripts. It is for looks only. Note that TDM is trying to establish the expectation that decorative doors that cannot be opened do not have handles (though not all maps follow this).

I will call this ''multiple handles'', see more below.

These can also be useful on brush doors created in the editor that may be very thin or very wide.

*'''''Double door handles''''':
These are models have have a handle inside and outside. The bonus is that they only use one entity. Maps are limited to about 4,000 entities but when you count lights, AI, sound speakers, ect... you can run out of entities quickly on a large map. If you plan on building a large map this is the way to go, even in a small map they have benefits, namely that you only have to attach one handle per door.

Whether you decide to use a single handle or a double handle you must first follow the instructions below and attach one handle first. If you choose a double handle, follow the instructions below and you are done. If you choose a single handle type follow the instructions then also follow the ''multiple handle'' instructions for the second handle.

Both single and double handle types can be found in two places. The model viewer which will create a static model good for show, you can manually add props to make them work OR you can look in the entity browser.
Using a handle from the entity browser saves you a little bit of time as some props are already added, you just need to add the frob_peer names for the doors/handles and the door_handle name to the door.

=== Adding a working model door handle===

Quick summary:
* Create a model or brush handle and make it an ''atdm:mover_door_handle'' entity.
* Position it on your door. Use the opposite side from the door's multicolor X-Y-Z indicator (highlight the door to see it) if it's not obvious which side it goes on.
* '''Bind''' the handle to the door (bind <doorname>)
* It should now be a working handle though may need adjustments of rotation etc. see later.

Important: read preceding section on door handle types and performance issues first.

This works with both a model door and a brush door:

'''Rotation''':
* By default the door handle entity rotates ''anti-clockwise'' (looked at from the front) then springs back. A ''double handle'' model is OK but two singles (see ''Multiple door handles'' below) need more care as only one is the functioning entity and the other is just attached to it. So anti-clockwise is fine for a door with its hinge on the left and the handle on the right - the handle will rotate down then spring back. If you put the functioning door handle on the other side you will have to change the default ''rotate'' property from -45 0 0 to 45 0 0. '''''Therefore it is easier to generally put this handle on the side of the door where the hinge is on the left and the non-functioning attachment handle on the other side.'''''
*If your door only needs one handle, eg, a cupboard door, and from outside its hinge is on the right then you will need to change the ''rotate'' property of the handle as described above.

'''''The functioning handle entity:'''''
* Create an entity door handle (movers folder) or create a brush or model handle and assign it the entity ''atdm:mover_door_handle''.
* Position it where you wish on your door.
* '''Bind''' the handle to the door, by adding the "bind" spawnarg to the handle.

You now have a working door handle with default properties.

*'''Multiple door handles''':
Now that you've got a handle attached to one side of the door it is time to add one to the other side (unless you used a double handle).
* Create the new handle. The single handles come in left and right persuasions. A door needs a left facing handle on one side and a right facing handle on the other, so if you have already added the left handle create a right handle and line it up on the other side of the door.
* Name this handle. I prefer to keep a naming convention for each door and it's respective handles, it makes things alot easier. The door is named '''My_Door_1''', the first handle is named '''My_Handle_1''' so name the second handle '''My_Handle_1_1'''. This will make it stay with the first handle in the entity list. This is important to keep organized. If you name it My_Handle_2 then when you get to another door named My_Door_2 you'll be confused.
* Place and '''bind''' that handle to your door.

You now have two single door handles on either side of the door that rotate together as if they were physically attached.

'''To add a brush to a brush door''':
* Select the new brush ''and'' the brush door all together; ''the entity '''must''' be selected '''last'''.''
* Use {{menu|Edit|Reparent primitives}}. This ensures the parent entity adopts the new item(s).
* If you have trouble selecting them in the orthoview because other brushes, etc. get selected then try in the camera view or as a last resort move them temporarily to an open area (but keep them in the same positions relative to each other.) Use {{key-shift}}+{{LMB}} on new item(s) then {{key-shift}}+{{LMB}} on main entity. Once they are all selected, use the {{menu|Edit|Reparent primitives}}.

'''To add ''model'' static items''': knockers, hinges, static handles etc. to a ''Model Door'':
* Select item
* Right click in orthoview and select ''Create Entity'' then <code>entity func_static</code>
* Position it where you wish on your door.
* To synchronize this with your particular door you need to add the property ''bind'' and the individual door name to the brush entity. To do this...
** Select the model door.
** In the entity inspector, select the ''name'' line
** Select the bottom line in the input box ''below'' the properties window.
** Copy the name
** Deselect the door with {{key-esc}}
** Select the brush entity
** Add a property "bind" to it.
** Change the value of the property by pasting in the door name
** Click {{check}} or press {{key-enter}}

'''To add ''brush'' static items''': knockers, hinges, static handles to a Model Door:
* This method is not ideal but it seems to work OK.
* Select the brush.
* Right click in orthoview and select Create Entity then ''atdm:mover_door_handle''
* Position it where you wish on your door.

To synchronize this with your particular door you need to add the property ''door_handle'' on the door, and give as the value the name of the brush you just created.

This brush turns like a handle. To stop it:

* Adding ''rotate 0 0 0'' or disabling the handle script won't help.
* Add a real working handle (as in the section above ''To add a working model door handle...'' and it must be added LAST.)

If you don't want too see a real working handle added maybe try another tiny brush with the handle function and hide it inside the door?

===Locking Doors===

To lock a door check the ''show inherited properties'' in the entity inspector for a ''atdm:mover_door'' entity and you should see the ''locked'' property. Select it and in the input box below the properties you can change its value:

* 0 = unlocked (default)
* 1 = locked

If locked it will require an entity that is associated with it to be able to act as a key to unlock it.

Currently door handles on locked doors will rotate when frobbed, they will bounce back though and the door will stay locked until unlocked.

===Keys===

Assigning specific keys to specific doors is simple.

* It is recommended that you create an existing key entity. These keys have all required props, they just need to be named.

Alternatively you can create a key from the Model Viewer and want it to be useable
* Make sure it has the properties:
useable 1 [so it can be used by the door]
frobable 1
inv_name <unique name>
inv_category Keys
inv_target player1
inv_icon guis/assets/hud/inventory_icons/<icon name>
inv_stackable 0 or 1 where 1 can be used on all copies of the same key so they show as one entry in the inventory with a total.

Add to the door the property <code>used_by</code> with the name of the key as the value. Multiple keys can open the same door by using several <tt>used_by</tt> spawnargs:

"used_by" "doorkey_1"
"used_by1" "doorkey_2

==== Keys Carried by AI ====

So you have a door and you have a guard AI and you want the guard to be able to open/close/lock the door, but you also want the player to be able to pickpocket the key. Keys can be attached to AI in two ways.

''The Def_Attach Method''. This method is the best one for doors that you expect the AI to operate. It uses spawnargs to spawn the key at game start.

*"def_attach6" "atdm:prop_silverkey" // the entity to spawn - in this case a key.
*"pos_attach6" "belt_back_right" // where the key will spawn on the Ai.
*"name_attach6" "door_key" // this gives 'attach6' arg the name "door_key" and is the name the arg "used_by" will need, eg: "used_by" "door_key"
*"set inv_name on door_key" "Door key" // The name the key get when the play adds it to their inventory.
*"set name on door_key" "door_key" // here it gets a name to be used in the map in general.

For more info on this method, see [[Attaching Props to AI]].

''The Bind Method''. This lacks the animation finesse of def_attach, but does let you see the key in DR. The method is particularly helpful in, say, adding a second key to an AI in the back middle of a belt. The AI cannot use a bound key to open a locked door; the workaround is to fake it with "can_unlock" as discussed further below. Or to use bound keys mainly for items the AI will not attempt to open, such as hatches, duct covers, or chests.

* Load a key entity
* Position where you want it in relation to the AI, and bind it to them (i.e., "bind" "<AIname>")
* Add the spawnarg "bindToJoint" "Hips" (or another location like LeftHips_Dummy; see AI for list)
* Adjust existing spawnargs accordingly (that is, be sure the name and door's/chest's "used_by" match, if you aren't using a prefab chest with key). This is for the benefit of the player after pickpocketing the key; as stated above, the AI itself can't use it for unlocking.

For more info on this method, see [[Attaching_Items]] and [[BindToJoint]].

====Keys Carried by Player====

With a door's key selected in your inventory and the door highlighted, you can...
* unlock it (which will also auto-open if enabled) by either frobbing it or hitting the Use key (typically U or Enter).
* lock (or relock) it via the Use key. Why do this? To avoid pursuit, or to lure guards into a room, and then lock them in (if they don't have a key or specific can_unlock powers).

====Master Key for Testing====

By default, ALL locks can be opened by any key named ''key_master''. Just create a key in your map, name it ''key_master'' and it becomes a master key for use while testing. Add inv_map_start 1 to it so it is in the player inventory at game start. Remember to delete it when your mission is finished.

====Automatically Removing Keys from Player Inventory After Use====
If a fan mission has a lot of keys it can clog up the player inventory. If the key is single-use, it can be useful to automatically remove it from the player inventory after use. Below is a way to do it using a simple setup and a generic script function that can be used for multiple doors.

=====Generic Version=====

You'll need the following entities, preferably set up near each other in your map:
* The door entity itself
* A trigger_count entity
* An atdm:target_callscriptfunction entity
* some random entity for the target_callscriptfunction to target (explanation below)

The below diagram shows the spawnargs and targeting required for the setup:
[[File:Key remove2.png|left|thumb]]

<div style="clear: both"></div>
The script being called ('openDoor') is defined in fms/<mapname>/maps/<mapname>.script and looks like this:

void openDoor(entity target, entity door, entity callscriptfunction)
{
string keyName = door.getKey("used_by");
entity key = sys.getEntity(keyName);
$player1.replaceInvItem(key, $null_entity);
}

Explanation as follows:

'''For the door:'''
* '''trigger_on_open''' spawnarg: The door is configured to trigger its targets when it opens
* target '''trigger_count''' entity: this is the entity that is triggered when the door is opened
* '''used_by''' spawnarg: This names the key entity required for unlocking the door
* The other spawnargs are just the usual for setting the door as locked and unpickable

'''trigger_count entity:'''
* When triggered, this entity will in turn trigger the script that removes the key from the player inventory.
* '''count''' spawnarg: This is set to 1 because we only want the key removal script called once - the first time the player opens the door.
* this entity targets the atdm:target_callscriptfunction, which contains details of the script to execute

'''atdm:target_callscriptfunction entity:'''
* '''call''' spawnarg: This is the name of the script function to call
* '''foreach''' spawnarg: This version of the script event provides access to the 'activator', or the entity that triggered it (in this case, the door). Using that information we can obtain the key name. See [[A to Z Scripting: Ways of calling a script#target_callscriptfunction|here]] for details.
* '''target any static entity''': For this version of the script event to work, the target_callscriptfunction entity needs to target something. This can be any static entity in the map (i.e. one that won't get removed or anything). I usually just target the nearest entity (e.g. a light or a lamp, or a model). This provides no functionality in the context of this tutorial, it just satisfies the conditions of the script event.

'''The script:'''
* Pretty self-explanatory. The script gets the name of the key entity via the '''used_by''' spawnarg on the door, retrieves the key entity, and then replaces it in the player inventory with a null entity, effectively removing it.
* Any door can use this script as its generic, although they will need their own trigger_count entities. In theory they could share the same target_callscriptfunction entity, but that might become inconvenient - up to the mapper.

=====Simpler, No-script Version=====
This is similar to above, but is more limited. You need to hard-code the key name as a spawnarg on an atdm:target_itemremove entity as the key name can't be automatically determined like in the above script. This makes it slightly more error-prone as we're naming entities in more than one place, but ideal if you're uncomfortable with scripting.

[[File:Key remove4.png|left|thumb]]
<div style="clear: both"></div>

Explanation as follows:

'''atdm:target_itemremove entity:'''
* '''unique_item ''' spawnarg: The name of the key to remove from the player inventory

===Lockpicks===
''by Baddcog''

There are two lock pick types.
*'''s'''=snake
*'''t'''=triangular

A lock can be set with many pins. Each pin has a click sequence and each needs a designated lockpick type (see above). Keep in mind that the lockpicking in The Darkmod is much more involved than in T2 or T3. The player has to listen to sounds or watch a handle or lockbar to know when a lock is pin is picked.

This means that authors can be very evil and really frustrate the player, in which case their missions will probably not be played. So be nice to the player and don't waste your time. Use simple locks for the most part and save complicated locks for important sections and to build tension. Don't make the player have 20 pins to pick all with different lockpicks. In most cases 1 or 2 pins will suffice and it isn't necessary to use both lockpicks on every lock.
Also try to include a lock lever on lockboxes or chests, door handles will rotate as the pins are being picked. This gives the player visual clues to help with the picking (and essential in noisy environments where you can't hear the clicks.)
IMO this system is a huge leap foward for lockpicking but also has the ability to completely frustrate the player as stated above. Keep this in mind when designing your lockpick systems.

These props go on the door itself, or the lid of a chest, eg,
*'''lock_pins''' 1327
*'''lock_picktype''' stts

The lock_pins property specifies how many pins each lockpicktype has.
The lockpick_type property specifies how many times the player has to switch picks and which pick they have to use. You can see there must always be an equal number of lock_pins and lock_picktypes specified

So looking at the example above we have lockpick_type s(snake), t(triangular), t(triangular), and s(snake). The player will have to use these lockpicks in this order. Once the snake lockpick's pins are open the player can advance to the triangular pick and so forth.
5 is added to every click sequence so 5 is the minimum click pattern even if you set it to 0.
In the example above the lockpins specify in order which pick types have how many pins, so the s pick has 1 + 5 = 6 clicks, the t pick has 8 and so on.
The above is a difficult lock and to avoid annoying the player it is best only used rarely on a special lock like an important big vault door. Ordinary footlockers and common doors can be just 1 or 2 click sequences, eg, lock_pins 2 and lock_picktype t means the player uses one pick and listens for the end of one sequence of 7 clicks.

lockpick_rotate - is placed on the door. It is the amount the visible rotating handle or pin rotates while picking. For a rotating handle or lockbar normally ignore this and leave the default. During lockpicking it oscillates and progresses to the normal full turn of the handle. Example 0 45 0.

lockpick_translate - is placed on the door. It is the amount the visible handle or pin moves in a straight line while picking. Use this if you have eg, a lockbar that you want to move in a straight line and not rotate, eg sliding catch. Example 0 -5 0

By default, doors are pickable. If you don't set up the above lockpick spawnargs then it can't be picked. So there is normally no need to enable lockpicking - just set up the above spawnargs. There is a ''pickable'' spawnarg set to 1 by default. If set to 0 then the door becomes unpickable. But hard to think of an application except in testing or perhaps a special custom situation where it is switched by script perhaps.

===Open, Partially Open, or Closed Door at Game Start===

By default, doors are closed at game start. If you want a door to be already open or partially open then do the following.

'''Note well: Create all doors in their ''closed'' position. Adjust as follows and they will automatically be at the open position when game starts.'''

Already Open Rotating Door:
* Select the door.
* Select the entity inspector
* Check ''show inherited properties''
* Select the ''open'' property
* Edit the value to 1 in the input box below and tick the check button
* The door will now be fully open at game start.

* If you want it only partly open:
* Make sure its ''open'' property is set to 1 as above.
* Right click the entity inspector and select ''add property''
* Click the + sign on the left of the top line where atdm:mover_door is listed to open the folder. (if atdm:mover_door is not listed then the entity was likely changed from eg, func_static. If so, save the map and reload to update the add property list)
* scroll down, select ''start_rotate'' then click {{ok}}
* This adds it to the property list.
* Now select ''start_rotate'' in the property list.
* Edit the bottom line of the input box ''below'' the properties window to the angle you want in the same form as described in the ''Rotate Direction and Open Angle'' section. So for example, to have a door that has a fully open default ''rotate'' value of 0 90 0 to start only half open you would give it a ''start_rotate'' value of 0 45 0.
* In a similar way add the property ''first_frob_open".
* Set it to 1 and a partly open door should then open fully on the first frob.
* Set it to 0 and a partly open door should close on the first frob.

Already Open Sliding Door:
* Select the door.
* Select the entity inspector
* Check ''show inherited properties''
* Select the ''open'' property
* Edit the value to 1 in the input box below and click {{check}} or press {{key-enter}}
* The door will now be fully open at game start.

* If you want it only partly open:
* Right click the entity inspector and select ''add property''
* Make sure its ''open'' property is set to 1
* Click the + sign on the left of the top line where atdm:mover_door is listed to open the folder.
* scroll down, select ''start_position'' then click OK. (if atdm:mover_door is not listed then the entity was likely changed from eg, func_static. If so, save the map and reload to update the add property list)
* This adds it to the property list.
* Now select ''start_position'' in the property list.
* Edit the bottom line of the input box ''below'' the properties window to the position you want in the same form as described in the ''Sliding (Translation) Amount and Direction'' section. So for example, to have a door that has a fully open default ''translate'' value of 0 50 0 to start only half open you would give it a ''start_position'' value of 0 25 0.
* In a similar way add the property ''first_frob_open".
* Set it to 1 and a partly open door should then open fully on the first frob.
* Set it to 0 and a partly open door should close on the first frob.

===Rotation Centre, Pivot, Hinge point===

The centre of rotation of a door is at the origin point of its entity and the door rotates with reference to the orientation of that origin point, not the world map. See ''Rotate Direction...'' for more about that. This section only deals with the ''position'' of the rotation centre in the door.

Model Door Centre of Rotation:<br>
The centre of rotation of a model door cannot be changed within Dark Radiant. Because a model door rotates around the centre 'spine' of its back edge this will cause clipping (penetration into solid) as in this example (where the door is set to open to 89 degrees for clarity):<BR>[[Image:modelClipping.jpg]]<BR> So care is needed with placement. You will not normally position a door right next to a wall as in the example but against a shallow frame so clipping will barely be noticeable but either way it can be fixed. You can correct it by adding a translation (see ''Sliding (Translation) Directions'') value of half the door width in the direction of the door handle. This will gently move the door out as it rotates to clear any solid on that side as in this diagram:<br>
[[Image:DoorClip.jpg]]<br>
Half a door width will typically be about 2. Any 'attachments' such as door handles will still synchronize with the door movement whether the door is rotating, sliding, or both.

Brush Door Centre of Rotation:<br>
The centre of rotation of a brush door ''can'' be changed. The default origin point of a brush is at its centre. Therefore a default rotating brush door will rotate around its centre when you first create it. So, mappers will commonly need to move that rotation point to a corner or even to some other offset position for example, for an openable window using the door function.

Put simply, to move the rotation point of a brush door you need to move the entity origin relative to the brush(es.)

Moving the entity origin (centre of rotation) relative to a brush door:

* Select the brush door
* Select ''Vertices mode'' (default shortcut key is {{key|name=V}} or button on top toolbar 'Select Vertices')
* Drag the door's entity origin to the point where you want the door to rotate. This should be on the corner on the leading edge side (the side to where the door is opening.) to avoid clipping as in this diagram....
[[Image:getCorner.jpg]]
* You should now find that door rotates around that point.

===Rotate Direction and Open Angle===

By default, rotating doors open anti-clockwise (viewed from above) by 90 degrees from the start orientation. If you want to change this edit the ''rotate'' property in the entity inspector. Don't confuse this ''rotate'' property with the ''rotation'' property. In the entity inspector remember that to see the inherited rotate property you must check the box 'Show inherited properties'.

The three values shown in the rotate property are degrees from the closed position around Y Z X (absolute map axes Front, Top, Side views in DR's ortho view.)

* Positive Y = Open clockwise (Dark Radiant grid front view, looking north)
* Negative Y = Open anti-clockwise (Dark Radiant grid front view, looking north)

* Positive Z = Open anti-clockwise (Dark Radiant grid top view, looking down)
* Negative Z = Open clockwise (Dark Radiant grid top view, looking down)

* Positive X = Open anti-clockwise (Dark Radiant grid side view, looking west)
* Negative X = Open clockwise (Dark Radiant grid side view, looking west)

There is a problem when you come to rotations that are not around the main Y Z X axes of the map, for instance a drawbridge that lowers down to the south east. You might think you can combine Y Z X values to get the result you want - and this can be done (for south east use 45 45 90) but it is a bit of a kludge and the drawbridge twists eccentrically as it lowers (though it arrives correctly!)

The values are in the range -179 to +180. Positive values give an anti-clockwise opening rotation (looking down from above) and negative values give a clockwise opening rotation. The value 180 is unique in that it continues in an anti-clockwise rotation when closing rather than returning clockwise so might be used if you can think of some object that might need such a motion when frobbed!

Edit the rotate value by selecting it and using the input box at the bottom and clicking the check(tick) button. That will change the angle the door will open to. Note that the line with the original default of 0 90 0 will still be there but your new entry will be added on a separate line and that is the one that will work in the game. CAUTION: when adjusting later make sure you have your new line selected and not the original! If you do it will appear to change but your first setting will remain unaltered.

Examples:
* 0 90 0 = Opens anti-clockwise round the entity's 'vertical' to 90 degrees - typical default vertical door.
* 0 0 90 = Lowers a drawbridge from the entity 'vertical' to horizontal.
* 0 0 -45 = Opens clockwise by 45 degrees viewed from the east side. This might suit a skylight in a sloping roof.

'rotate' cannot be combined with translate motions (see [[#Sliding (Translation) Amount and Direction]]) in one door; you need to bind one door to another and link they by targetting one to the other. By that means you can produce exotic and useful motions. A door opening against an upward-sloping floor can thus have a ''lifting hinge'' and raise up slightly to clear the floor; a door can rotate towards you and slide back to one side very effectively.

===Sliding (Translation) Amount and Direction===

By default a Dark Mod door will rotate open. For most sliding doors you want to stop them rotating as well as make them slide. You cannot delete (remove) the ''rotate'' property - you have to set the ''rotate'' property to 0 0 0 to stop a door rotating (see ''Rotate Direction and Open Angle''.)

Now edit the ''translate'' property value by selecting it (remember to have inherited properties box checked) and using the input box at the bottom and clicking the check(tick) button. That will change the distance the door will slide to. Note that the line with the original default of 0 0 0 will still be there but your new entry will be added on a separate line and that is the one that will work in the game. CAUTION: when adjusting later make sure you have your new line selected and not the original! If you do it will appear to change but your first setting will remain unaltered.

Typically (but not always) you will want your sliding door to slide the width of the door. The three values in the translate property by default are 0 0 0 and are X Y Z ''absolute map'' values (irrespective of door orientation) where:

* Positive X = Slide East (Right side of Dark Radiant grid in top view)
* Negative X = Slide West (Left side of Dark Radiant grid in top view)
* Positive Y = Slide North (top of Dark Radiant grid in top view)
* Negative Y = Slide South (bottom of Dark Radiant grid in top view)
* Positive Z = Slide Up (Top of Dark Radiant grid in side views)
* Negative Z = Slide Down (Bottom of Dark Radiant grid in side views)

So for a 50 unit wide door you want to slide fully to the east you would use 50 0 0 for the translate property values. A 100 unit portcullis sliding vertically up would need 0 0 100 to be fully raised.

=== Doors Collision/Push Behaviour ===
Doors push all entities by default, except for the player. Doors will also stop moving when anything blocks their movement. However, this default behaviour can be changed by setting appropriate spawnargs:

Set '''push_player''' to '''1''' to let the player be pushed by this door:
"push_player" "1" // Push the player too (default is off)

By default '''stop_when_blocked''' is set to 1 and if a door is blocked by an entity then even if the entity is removed afterwards, the door stays where it is. The next frob will close the door.

Set '''stop_when_blocked''' to '''0''' to prevent the door from ending the opening sequence when anything blocks its way. It will still pause - but continue to open if the block is removed.
"stop_when_blocked" "0" // door keeps moving after being blocked (default is off)
With this setting, doors will still stop at blocking entities (the player, for instance), but will continue to move when the entity moves out of the way.

There is another spawnarg which stops a door pushing a moveable. Apply this to the ''moveable'', not the door...

"notPushable" "1"

===Door Sounds===

There are multiple ways to put sounds on doors.

''snd_open'' <br>
Sound is triggered as the door begins to open.

''snd_opened'' <br>
Sound is triggered when the door finishes opening. Defaults to "nosound".

''snd_move''<br>
The sound plays while the door moves. Defaults to "nosound".

''snd_close'' <br>
Sound is triggered as the door finishes closing.

The following sounds should be left on the default sound in most cases so players clearly know what is going on:

''snd_locked''<br>
The sound played when a player or an AI tries to open a locked door.

''snd_unlock string''<br>
The sound played when a door is unlocked.

You can silence any of these sounds by setting the following properties as shown:

''snd_open nosound''<br>
''snd_close nosound''

Don't just use a dash - as it seems to cause a sound of its own.

===Sound Propagation through Doors and Doorways===

''This information will change significantly with the release of 2.0. See'' [[Controlling Sound Loss Across Portals]]

The sound volume reduction to the player (ie, the sound the player hears) is fixed and constant in a cvar which adds a distance factor to the original sound. It is recommended that you do not change that because it will affect other FMs. Currently there is no way to change the way that sound to the player is reduced through doors and doorways.

Sound propagation to AI, eg, impact sounds or guard yells is treated separately:

Sound propagation to AI relies on visportals. For details study [[Sound Propagation: Part 1]] and [[Sound Propagation: Part 2]] as well as [[Visportals]] This tutorial will just cover the relevant sound and sound propagation ''properties'' of doors. If you set the ''show inherited properties'' box in the entity inspector you can see them as described here.

Remember, the following have no effect on what the player hears through a door or doorway.

''loss_open''<br>
Drop in sound volume in dB propagated to AI (not player) when going through an open door. (default 1dB)

''loss_closed''<br>
Drop in sound volume in dB propagated to AI (not player) when going through a closed door. (default 15dB) You would want to set this very high to block all sound with a thick door but very low for a barred gate for example.

''loss_double_open''<br>
Drop in sound volume in dB propagated to AI (not player) when going through double doors when only one is open. (default 1dB)

There are also various sound properties for lockpicking:<br>
''snd_lockpick_pin_1 through 14'' and ''snd_lockpick_pin_success''

===Allowing the Player to Interrupt Door Motion===

The door property ''interruptable'' determines whether a door can be stopped by frobbing while it is opening or closing. It is enabled (i.e., set to 1) by default. Then the player, by frobbing to start the normal opening, then frobbing again to interrupt, can open a door to any position, e.g., slightly ajar to peek through. Another frob will begin closing, and so on with any additional frobs to stop/reverse-direction.

Be aware that an rotating-style door, when left ajar, will subsequently open or close more slowly than normal in an angular-velocity sense. It instead takes the same time as a full (uninterrupted) opening or closing would take in seconds, as given by ''move_time'' discussed next.

===Speed of Door Opening and Closing===

Rotating Door Speed:<br>
The time a rotating door takes to open or close is set in the ''move_time'' property, no matter what its maximum open angle may be. So with rotation set at, say, 150 degrees the door just opens faster than at, say, 80 degrees. To change this value, make sure the door is selected then...

* Right click the entity inspector and check ''show inherited properties''
* Scroll down, select ''move_time''
* Edit the second line of the input box ''below'' the properties window to the time you want.
* The time is in seconds and decimal fractions can be used. The default is currently 1.75 seconds.

Sliding Door Speed:<br>
The speed of a sliding door is set in the ''translate_speed'' property. To add this, make sure the door is selected then...

* Right click the entity inspector and check ''show inherited properties''
* Scroll down, select ''translate_speed''
* Edit the second line of the input box ''below'' the properties window to the speed you want.
* The speed is in Dark Radiant grid units per second.
* The default is 0 and if set to this then the door slides open in one second whatever the distance, great or small.
* CAUTION: It is assumed ''translate'' has been changed from its default value of 0 0 0. If not, a non-zero ''translate_speed'' may cause problems.

===Visportals and Doors===

A visportal face surrounded by solid at its edges and in contact with a door is closed when the door is closed and enabled when the door is open. In most cases you will place a visportal in contact with a working door unless you can see through the door (such as a true glass door or barred gate*.) For full details see [[Visportals]].

''*As of 2.0 it is possible to make visportals that remain transparent when closed for gates and windows. See'' [[Controlling Sound Loss Across Portals]]

==Auto-Closing/Opening Doors==
Doors that automatically close after being open for some time are easy to setup: Each frobmover entity supports these spawnargs:

;"auto_close_time":Set this to something >= 0 to let the mover automatically close (again) after this time when being fully opened (measured in seconds). Defaults to -1, which means 'do not autoclose'. The event is also activated when the mover starts at the open position at map start.
;"auto_open_time":"Set this to something >= 0 to let the mover automatically open (again) after this time when being fully closed (measured in seconds). Defaults to -1, which means 'do not autoopen'. The event is also activated when the mover starts at the closed position at map start.

<div class="toccolours mw-collapsible mw-collapsed">
Before auto_close_time and the AI Door Management spawnargs next were provided, a more laborious method was used to auto-close doors as if AI were closing doors behind them. Hit "Expand" to review it.
<div class="mw-collapsible-content">I have one door that I particularly want the AI to close as there is a bit of frame lag inside if not. So I set this up and it works good as an auto-closing door - not as good as a true AI closing door as it will auto close when the player goes through as well but it does look very effective to see AI going through and closing the door behind them. Not tested exhaustively so I don't know if there could be any downside. Here's what to do....

First a quick summary to make it more clear:

'''''A trigger_relay is used both as a relay AND carries a stim. We put the trigger_relay with its stim in the path of the open door. The door has a response property. When it opens and contacts the stim its response is to send a signal back to the relay. The relay pauses then closes the door...'''''

* First, optionally give your door a suitable name like autodoor1, whatever.
* Copy that name to the clipboard.

Next we need a relay with a delay:

* Create entity > darkmod > trigger_relay

* Place it roughly at the position the door will be at when open and to be on the safe side 3/4th of the way to the far end of the door (not the hinge end) to give max distance from the close door.

* Add the property 'target' and paste in the door name you just copied.

* Give the relay itself a name, eg, autoDoor_relay_1, and copy that name to the clipboard, you'll need that too in a bit.

* Add the property delay and the value 3 - this is the delay in seconds before the door will close; 3 seems about right but 2 might be worth a try because to that 3 is added a random value between 0 to 0.5 seconds from the Time Interval we entered for the stim firings.

* Add the property 'wait' and the value 3. This is the time before it can work again in seconds. If you set it too low then in theory the door might trigger again but in this situation I don't think it's possible. Too long, eg, one minute, and it won't work if the AI goes back through the door before then. If this value is -1 then the whole thing will only work ONCE so might be used for an AI who goes through once, closes it behind him, but you don't want it to be an autodoor thereafter.

That's the relay, now we add a stim to it:

* Still with the trigger relay selected, go to {{menu|Entity|Stim/Response}}

* Custom stim tab.

* Click Add stim type, select the new custom stim type you just made at the bottom of the list and type in eg, autoDoorStim at top right in the input box.

* Click the stim tab and the little drop down arrow against the 'type' selector at bottom left and you should see your new custom stim name. Select it.

* Select the new autoDoorStim in the list and on the right you need only type in the radius box 15.0 There is quite a lot of room for error. I had it working on 10 and also on 25. The value should be less than the distance to the closed door else it will trigger open! But no so small that the door might not reach it.

* Select the check box for Time Interval and enter 500 (millisecs.) This is so it doesn't keep firing more frequently than is necessary. This stim will be firing all through your mission whether the door is used or not so if you had dozens of these then maybe it would affect performance. Too big a number and there may be a long delay before the door shuts - but it will be random depending on the next time the stim happens to fire. We'll control the delay we want more precisely later.

* Click {{ok}} to confirm it.

That's the stim set up, now for the response to it which is put on the door....

* Select the doorm, then use {{menu|Entity|Stim/response}} and select the response tab.

* Click the little drop down arrow against the 'type' selector at bottom left and you should see your new custom stim name. Select it.

* Right click in the big ''Response Effects'' box on the bottom right of the panel.

* Add New Effect and you should get a default 'Activate Response' response added to the list. Double click it.

* In the Effect selector at the stop select 'Trigger'

* in the Target box, paste in the name of the relay you copied or you can select it from the list at the little arrow.

* Leave the Activator box empty.

* Click {{apply}} and then {{ok}} on the main S & R panel bottom right.

It should now work. No need to wait for an AI, just frob the door and watch it close itself. If not, check the position of the stim brush is close to where the door stops when open.</div>
</div>

==AI Door management==

By default AI will open doors and close them behind them. Here are some spawnargs '''on the door''' the mapper can use to modify that behaviour:

;"ai_should_not_handle" :If set to 1, AI will not attempt to handle it and add it to the forbidden areas (so that it doesn't try to path through). They might still walk through the door when it is open though. Useful if you have some special use door that you don't want the AI to operate.

;"ai_should_not_close" :If set to 1, AI will not close the door behind them unless it obstructs them.

;"canRemainOpen" :If set to 1, it's the same as "ai_should_not_close, with the added behavior that this is ignored if the door needs to be relocked, or the door is marked "shouldBeClosed". '''(This spawnarg is available starting in TDM 2.02.)'''

Spawnargs '''on the AI''' that the mapper can use:

;"canCloseDoors" :Added in 2.12. Defaults to 1. If set to 0, the AI will not close doors after passing through them.

To get AI to unlock/relock specific doors there are two methods:

1. Provide the AI with the key, as detailed in the def_attach method in [[#Keys_carried_by_AI]] above.

2. Add the following spawnarg/value to the AI:

;"can_unlock" ''<doorname>''

For additional doors on the same AI use ''can_unlock1 doorname', `can_unlock2 doorname' etc. '''Do NOT use can_unlock_1.'''

If both (1) and (2) are used, then the AI can still go through the door after the player pickpockets the key. Otherwise, unless someone else opens the door for the AI, a typical sequence is that the AI checks their pockets for the missing key, stalls a bit at the locked door, and then (with now-better pathing algorithms) the AI uses an alternate route to the next path_corner, or "mentally" skips ahead in the route to next reachable node and goes there.

===Door Handling Positions===

It is also possible to set custom door handling positions for the AI. This is especially useful when the standard routine that lets the AI choose their standing positions while opening and closing the door fails, leaving them standing still, or circling around in front of the door helplessly.

Place a movers > ''atdm:door_handling_position'' entity where you want the AI to stand while opening/closing the door from this side.

On the door, you need to set the spawnarg "door_handle_position" "name_of_door_handling_position". You can also place a ''door_handling_position'' on each side of the door, and the AI will automatically choose the right one. In this case, you need to set spawnargs with "door_handle_position_1" etc., and the corresponding names of the ''door_handling_position'' entities on the door.

The ''door_handling_position'' entities can also carry spawnargs that define the behaviour of the AI, which are useful for example for doors that can only be opened or locked from one side:

'''"ai_no_open"''' If set to "1", the AI will not try to open the door from this side (but will still walk through when the door is already open).

'''"ai_no_close"''' If set to "1", the AI will not attempt to close the door from this side.

'''"ai_no_unlock"''' If set "1", the AI will not be able to unlock the door from this side, but still use it when it is not locked.

'''"ai_no_lock"''' If this is set "1", the AI will not lock the door from this side.

===Door Controllers===

'''Available in TDM 2.02+'''

You can design a door so it's operated by buttons or levers or switches (aka ''controllers'').

A controller is simply an entity that targets the door. Typical examples of entities that can be used are:

* Buttons: atdm:mover_button
* Levers: atdm:switch_rotate_lever
* Switch: atdm:mover_lever
* Lock: atdm:froblock. (See also next section)

1. Set up the door in the normal manner. It can be a rotating door, a sliding door, a locked door, etc.

2. Turn off the "frobable" spawnarg on the door. ("frobable" "0")

3. Create a controller entity on each side of the door. If you're setting up a locked door using atdm:froblock, there's no need to put any locking information on the controllers. When the game starts, it will transfer any locking information from the door to the controllers.

4. Give each controller the door as a target.

Both the player and any AI that wants to use the door will use the controllers to operate it. Any key, "can_unlock", or lockpick settings you would normally use at the door are now used at the controllers.

Controllers and ''door_handling_position'' entities can be used on the same door, but in that situation the ''door_handling_position'' entities don't define where the AI stands to operate the door. They simply provide the "ai_no_*" spawnargs that define AI behavior on each side of the door.

If you wish, you could provide a controller on only one side of the door instead of both sides. Note that, since the door is not frobable, the player won't be able to operate the door from the non-controller side.

====More about Using a Separate "Froblock" Lock Plate====
''by Geep, 2021-22''

Froblock, just discussed as a controller method, actually predated the controller concept in TDM. Here we recap that earlier context, with an alternative treatment of highlighting, and thoughts on texturing and usage.

Suppose you want to have a lock plate (typically mounted on a door frame or wall) that opens a nearby door, where the door and lock plate highlight separately. A traditional way is to adapt the ''froblock'' method described under the "Making your own" section of [[Containers, Chests, etc.]]

Basically, your door is the "chest lid" (of class atdm:mover_door) and your lock is the "chest body" (of class atdm:froblock). Set the properties as described in the wiki. There is a stock texture (darkmod/door/keyhole_metal_001) you can use to decorate a surface of your lock plate, or a patch on it. This method is probably most apt for small hatches and grates designed for the player alone, and with no handles, or non-turning handles attached with "bind".

===AI and 'non-frobable' Doors===
Be aware that the 'frobable' spawnarg only applies to the player, not AI. If you set a door to be non-frobable (i.e. 'frobable' '0'), AI can still operate it by interacting directly with it, even if it has a controller. For example they will do this if:

* they are fleeing or chasing the player
* the door has a controller but the AI can't reach it (for example the controller is on the other side of the door)

The best way to mitigate this is to use Door Handling Position entities (see above) with the 'ai_no_open' spawnarg set on them.

===AI locking doors behind them===

If one AI is involved (no one else is in the queue), he'll lock it behind him if he had to unlock it in the first place.

Prior to TDM 1.08, if more than one AI is using the door at the same time (there's a queue), the first AI unlocks the door, and the last AI through will only lock it if it's marked "should_always_be_locked" AND they have a "can_unlock" for that door or they have a key for that door. The last AI to use the door doesn't know that the first AI found it locked, because that info is kept per AI, and not per door.

Starting in TDM 1.08, if the first AI in a door queue found the door locked, that information is remembered by the door and the last AI through uses it to relock the door, as long as they have a "can_unlock" for that door or they have a key for that door.

In the rare case where a door is set up to use door-handling position entities (necessary for AI to use sliding doors), either or both of those entities can have the "ai_no_lock" spawnarg, which means AI aren't allowed to lock the door from that side.

==Initially Blocking a Door - Partially or Fully==
''by Geep 2021''

Suppose you have a door that you want to start out either as unopenable, or able to open just a crack, then later, after something happens, be fully openable and operational. One method known to work:

* Create a moveable object that the opening door runs into and tries to push.
* Arrange that the far side of the moveable object is jammed against some immovable worldspawn.

Here's two specific examples that use a wooden plank moveable:

* In "Perilous Refuge", a plank blocks the door leading out of the player's starting location, until the player carries it away.
* At the end of "Away0" (WIP 2021), the player tries to open a door. But if preconditions aren't met, the occupant seems to let the door open only a crack and complains. Blockage is done by an unseen plank resting on the floor hitting a knob of worldspawn. Preconditions met causes a "$plank.remove()" script call.

Other methods that you might think would work but don’t:

* Block with a func_static object, or an unjammed moveable with "notpushable 1" set. In both cases, the door travels through the object.
* In advance, "grab" an unjammed moveable to make it appear "solid" to the physics engine. (This was tested by having the player manipulate it; if it had worked, a “grabber” script call might suffice.)
* Dynamically change the door’s "rotate" limit from script using "setSpawnArg"; this function would only work before you spawn the door, not afterwards.

(Others possibilities not yet tested:

* Change "rotate" using the "setKey" script function; for some spawnargs this works even after spawn.
* Create a moveable and bind it to the world entity.
* If you are mainly interested in initially blocking an AI from using a door: it's possible that the AI re-reads the spawnargs for what doors it's allowed to open. Try adding a frob Response to the key (Entity -> Stim/Response... -> Response) with an effect that sets the “can_unlock" spawnarg on that AI to "-".)

==Controlling a Door by Scripting==
''by Geep 2021''
===If Unlocked===

Simply use, for example with a door named ''door1'':

$door1.Open();
...
$door1.Close();

Alternatively, toggle it open or closed with:

$door1.frob();

If the door has "interruptable 1" (which is the default with atdm:mover_door), you can also frob() it twice to leave it ajar. Interpose and adjust a sys.wait(...) to tune it.
===If Locked===

You need to unlock it first. Changing the door's "locked" spawnarg value won't work. Instead you will use:

$door1.Unlock();

But there are complications. By default, the door has spawnarg "open_on_unlock 1". So, assuming you didn't change that, you'd think unlocking the door would open it. But this spawnarg will be ignored if the gamer has global menu option "Open Doors on Unlock" set to Off. Assuming you want to reliably have the door open, do this:

$door1.Unlock(); // MAYBE will open door too.
sys.wait(3); // If so, wait for door to fully open. Value may need adjusting based on door's speed
$door1.Open(); // Otherwise, open it now.

The wait is added, because otherwise, the opening begun by Unlock may be stopped by Open with the door only partially open. (Probably an alternative to using sys.wait here is to zero the door's "interruptable" spawnarg.)

==Doors as Triggers==

''by Ishtvan & greebo''

Doors (or any binary frob mover, buttons, levers, etc) now have the option to [[Triggers|trigger]] their target on closing or opening. (For definition purposes, a button is defined as "closed" in the state when it starts out and "open" in the state you press it down to. I know that's a little non-intuitive, but it came from deriving from doors).

New spawnargs on frob movers:
;"trigger_on_open" :If set to 1, this binary mover will trigger its targets when it starts out completely closed and is opened.
;"trigger_when_opened":If set to 1, this binary mover will trigger its targets when it is completely opened. Code defaults to 0.
;"trigger_on_close":If set to 1, this binary mover will trigger its targets when it completely closes after being open.

== Suspicious Doors ==

If you give a door the spawnarg '''"shouldBeClosed" "1"''', then AI will treat it as suspicious if they find the door open.

Doors with that spawnarg should work like this:

- an AI opening the door knows he's not to become suspicious if he opened the door

- nearby AI alerted by the open door will also not react if they can see the door, and can see the AI that opened it

- AI who come upon the open door later probably won't be able to see the AI that opened it, so they'll treat it as suspicious

- if the AI who opened the door comes upon the door later, and it's still open, and no one's touched it since he opened it, he'll see his name on the door and won't become suspicious. "Oh, crap. I forgot to close it earlier."

- If an AI comes upon an open door that should be closed, he should close it whether he becomes suspicious or not.

'''Post TDM 2.00:'''
- AI turn to look at a door they see opening. The player can crack open a suspicious door to peek out w/o grabbing the attention of a nearby AI. After 5s, the AI will notice the cracked open door. Non-suspicious doors can be cracked open indefinitely w/o nearby AI noticing.

==Slanted or Tilted Doors==
Slanted or tilted doors can be made as follows:

1) Place your door, preferrably one of the prefab doors, which have a model door and model handle and all the rotation spawnargs pre-set.

2) rotate and place the door+handle model into place you want it to be. Now, if you use the door in the game, the door will rotate around the world z-axis, and not the door model z-axis (which is rotated).

3) to get the door to rotate around the door model z-axis, you must place a model (any model will do, and it can be placed anywhere in the map). Rotate the new model into the same orientation your door model was rotated, i.e. if you door is rotated 45 degrees around the x-axis, do the same rotation on the new model.

4) bind the doors on the new model. This makes the doors start rotating along the new model origin (which is rotated the same way as the doors).

5) working slanted door.

Do note, that all the rotated objects need to be models (suspicion, not tested). You can export DR built stuff into a model using the DR ase exporter script. For custom doors, remember that the exporter places the model origin at the map origin if you do not choose the "place origin in the middle of the object" option.

Also note that the AI probably cannot use slanted doors and might get stuck (suspicion, not tested).

There is a link to a test map here:
http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/?p=395486

==Skins: A Wide Variety of Door Textures==

This is to remind you that as with many Dark Mod models, there is a wide range of extras skins (textures) available for door models. There are now several basic door entities of different sizes so choose your size first. Then enter the spawnarg: skin with any temporary value. Now select it and click the skin button at the bottom of Dark Radiant's Entity Inspector and you will find a large of range of skin textures from which to select to give you a choice of appearances for your door.

==Extra Notes==

''func_darkmod_door'' is no longer used (just in case you come across it in the Dark Mod forums or wiki.) '''<code>atdm:mover_door</code>''' is the entity to use.

{{tutorial-editing}}

Doors

2025-11-06T20:23:00Z

Frost Salamander: /* Generic Version */

{{todo}}
''Written by Fidcal'' ''edit Baddcog''

==Quick Summary==

Quick way to get an unlocked door in your map:

* Insert one of the prefab doors complete with handles and select its skin property and click the button to change its skin appearance to whatever you want. Set any other properties you need.

Alternatively,

* Create a door from the entity list
* Use the "skin" spawnarg on the door to change its appearance.
* Create a handle from the entity list
* Add the ''door_handle'' property to the door and give it the name of the handle
* To the door handle add the value frob_peer and use the name of the door.
* To open clockwise, change the ''rotate'' property from <code>0 90 0</code> to <code>0 -90 0</code>

==Introduction==

This tutorial explains how to put doors into your map using Dark Radiant, as well as adjust them and their properties.

The rest of this tutorial assumes that you have a basic understanding of using DarkRadiant. If you haven't done so, please go read the [[Dark Radiant Must Know Basic Intro]] article first.

Additionally:

* Up, down, right, and left in Dark Radiant's ''top'' orthoview are regarded here as the standard map directions of North, South, East, and West where useful for clarity.
* Where the term ''brush'' is used with a door it mostly also applies to a door made up of a group of brushes and/or patches.
* Where the term ''door'' is used it often will also apply to any object you wish to rotate when frobbed, for instance an openable window, box lid, or even more exotic objects that the imaginative mapper might conceive like a signal, engine part, toy, or whatever. So long as it needs to turn or slide just a fixed amount when frobbed then return when frobbed again then the following applies.

==Door types==

All tangible objects in Dark Mod are ''entities'', having either a pre-made model shape or else brush/patch(es). So there are two ways to create a door in Dark Radiant: as a model door or a textured brush door (or a hybrid of the two).

Models are ready made door objects but cannot within Dark Radiant (at the time of writing) be resized, rescaled, cropped or clipped whereas brushes are very flexible in that respect and can be worked into custom shapes for your map, including secret doors that blend into walls and other surfaces.

Most of the current door models are found in two places along with the door handles.
*Model Viewer: doors created from here will be static in the world and have no props other than material type.
You can add any props to them to make them working doors. If nothing else it is a good place to view the different size and skin options for the doors.
*Entity List: most of the door models can be found here. These doors have properties already assigned so they are ready to be used. Only one base door of each type is listed, create the size/hinge count door you want (2 hinge doors have a 'no hinge' skin). You can choose a skin for the door once it has been created in the editor with the "skin" spawnarg (use the model name of the door you want, taken from the model list, as its value). This is the easiest way to create a door. The same goes for door handles.

Remember also that door functions may be applied to objects other than doors, such as openable windows, drawbridges, gates, etc. In fact, anything that needs a partial rotation or slide when frobbed then return when frobbed again, such as a signal device. Lockboxes and chests use similar properties.

You can create one door/handle set and copy/paste it, but you need to take great care that all the name props are changed to match in each clone. Otherwise you get handles that fly off when a distant door moves, and handles that don't move.

==Creating a Door==

Put simply, to make a door you will be creating an 'entity with model' or 'entity with brush' or some variation thereof.

===Creating a Model Door===

There are several approaches to making a model door; the simplest is to create a door from the entity list; or create a door from the model viewer (good for static unusable prop doors).

'''Entity List''':

*Deselect everything in editor by hitting the Esc button
*Right-click an ortho view and select Create Entity
*Navigate to darkmod/movers/''atdm:door_...'', choose the door you want
*Click Add
*To change its appearance, add a "skin" spawnarg to the door, with the value being the model name of the door you want.

You now have a workable door in your level.

'''Model Viewer''':

* Right click in the orthoview, select ''Create Model'' then <code>darkmod</code> and select a door.
* Note that you can left drag the image in the ''Choose Model'' dialog to rotate it around.
* Click [[Image:Button ok.png]] and you have a static door.
* If you want to make it work (openable, frobbable) then:
** Select the entity inspector,
** Select the top classname line so it highlights
** Select the func_static line in the input box ''below'' the properties window.
** Edit <code>func_static</code> to <code>atdm:mover_door</code>
** Click {{check}} or press {{key-enter}}

Alternatively you can do it the old way:

* Create any temporary brush
* Right click in orthoview and select <code>Create Entity</code> then <code>atdm:mover_door</code>.
* Left lick the model name line in the entity inspector.
* Below it on the ''Entity Inspector'' panel you should now see a button 'Choose Model'
* Left click it, select a door model from the darkmod group.
* Note that you can left drag the image in the ''Choose Model'' dialog to rotate it around.
* The temporary brush was deleted.

In all three instances, you now have a working door with default properties.

Name your door by adding the prop (or modifing it) to name ''My_Door_1''. You can use any name that you feel is appropriate but all doors with handles attached ''must'' have their own specific name. Use the name My_Door_1 for your first attempt as it will be referenced when you get around to attaching handles (see below).

To add a handle and other adjustments, see [[#Customising and Adjusting Door Properties]] below.

===Creating a Textured Brush Door===

'''Tip:''' If unsure of size then you might insert a temporary human AI first to get a sense of height.

==== The simplest brush door: ====

* Drag out a new brush to the size required, eg, a seven foot high door is 84" x 1.1 = about 90 units in Dark Radiant.
* Give it a door texture from the texture browser (or wall texture for a secret door)
* Right click in orthoview and select ''Create Entity'' then <code>atdm:mover_door</code>

You now have a working door but it will rotate around its center. To move the rotation point to where you want the door hinges to be:
* Select the door and press 'v' or the ''Select Vertices'' button to enter vertex editing mode. The door's origin will show up as a small green square in the middle of the brush.
* In top-down orthoview, move the origin from the center to the corner of the brush. This is easiest in drag mode ('q' or the ''Resize'' button), although you can use translate mode ('w' or the ''Translate'' button) by manually selecting the vertex first.

==== Multi-brush doors: ====

More complex multi-brush doors can be created using the [[Clipper]] tool, CSG, etc. - this is not covered in this tutorial. Then assign <code>atdm:mover_door</code> for that whole brush structure. Also you can collect various brushes positioned together in relation to one another as needed, select them all, then assign <code>atdm:mover_door</code> for the group. All the brushes will be children of the <code>atdm:mover_door</code> entity and will rotate and be frobbable, etc. as one unit, as one door. To add further brushes or even model shapes later see the section on [[#Adding handles and other items to doors]].

Name your door by adding the prop (or modifing it) to name My_Door_1. You can use any name that you feel is appropriate but all doors with handles attached must have their own specific name. Use the name My_Door_1 for your first attempt as it will be referenced when you get around to attaching handles (see below). (repeated from above in case you didn't choose to create a model door)

=== Double Doors ===
Double doors are automatically recognised by the code when the doors are spawned. The prerequisite is that both doors are sharing/touching the same visportal. The spawnarg ''auto_setup_double_door'' (which defaults to "1") will take care of setting up the open/lock peer relationship between the two doors. The doors will open/close and lock/unlock along with each other as a result.

What happens behind the scenes: the doors are adding each other to their internal open_peer and lock_peer list, which causes the double doors to perform the same action when frobbed or used.

Note that ''auto_setup_double_door'' will not set the frob_peer relationship, i.e. each door will frob-highlight on its own without highlighting the other door. You'll need to add that spawnarg manually if you want to highlight the entire double door as one.

==Customising and Adjusting Door Properties==

Handles, lockplates, etc. can be added to doors and door properties can be adjusted for rotation, sliding, locking, and more.

Some of the door models have hinge plates and lockboxes that are reskinnable with a good variety of skins.

===Door handles and other door attachments===

'''Summary: just add the property ''bind'' with the door's name to the attachment and position it where you want it on the door. If it's a ''atdm:mover_door_handle'' then it automatically will work as a handle but you can bind virtually anything.'''
You can add handles and other items to doors such that they move correctly with the door whether rotating, sliding, or both and even if the door is not vertical such as a skylight or trapdoor.
Handle models come in two types, ''single handles'' and ''double handles''. A single handle is one sided, this means the handle will be inside the door or outside the door, but not both. A double handle has a lever on the inside of the door and a handle on the outside of the door. Each has benefits.

*'''''Single door handles''''':
Single door handles can be used on a static door, a door that's just for show that no AI's or the player can use. In this case you should just create a door handle from the model viewer, it will be static and have no properties such as scripts. It is for looks only. Note that TDM is trying to establish the expectation that decorative doors that cannot be opened do not have handles (though not all maps follow this).

I will call this ''multiple handles'', see more below.

These can also be useful on brush doors created in the editor that may be very thin or very wide.

*'''''Double door handles''''':
These are models have have a handle inside and outside. The bonus is that they only use one entity. Maps are limited to about 4,000 entities but when you count lights, AI, sound speakers, ect... you can run out of entities quickly on a large map. If you plan on building a large map this is the way to go, even in a small map they have benefits, namely that you only have to attach one handle per door.

Whether you decide to use a single handle or a double handle you must first follow the instructions below and attach one handle first. If you choose a double handle, follow the instructions below and you are done. If you choose a single handle type follow the instructions then also follow the ''multiple handle'' instructions for the second handle.

Both single and double handle types can be found in two places. The model viewer which will create a static model good for show, you can manually add props to make them work OR you can look in the entity browser.
Using a handle from the entity browser saves you a little bit of time as some props are already added, you just need to add the frob_peer names for the doors/handles and the door_handle name to the door.

=== Adding a working model door handle===

Quick summary:
* Create a model or brush handle and make it an ''atdm:mover_door_handle'' entity.
* Position it on your door. Use the opposite side from the door's multicolor X-Y-Z indicator (highlight the door to see it) if it's not obvious which side it goes on.
* '''Bind''' the handle to the door (bind <doorname>)
* It should now be a working handle though may need adjustments of rotation etc. see later.

Important: read preceding section on door handle types and performance issues first.

This works with both a model door and a brush door:

'''Rotation''':
* By default the door handle entity rotates ''anti-clockwise'' (looked at from the front) then springs back. A ''double handle'' model is OK but two singles (see ''Multiple door handles'' below) need more care as only one is the functioning entity and the other is just attached to it. So anti-clockwise is fine for a door with its hinge on the left and the handle on the right - the handle will rotate down then spring back. If you put the functioning door handle on the other side you will have to change the default ''rotate'' property from -45 0 0 to 45 0 0. '''''Therefore it is easier to generally put this handle on the side of the door where the hinge is on the left and the non-functioning attachment handle on the other side.'''''
*If your door only needs one handle, eg, a cupboard door, and from outside its hinge is on the right then you will need to change the ''rotate'' property of the handle as described above.

'''''The functioning handle entity:'''''
* Create an entity door handle (movers folder) or create a brush or model handle and assign it the entity ''atdm:mover_door_handle''.
* Position it where you wish on your door.
* '''Bind''' the handle to the door, by adding the "bind" spawnarg to the handle.

You now have a working door handle with default properties.

*'''Multiple door handles''':
Now that you've got a handle attached to one side of the door it is time to add one to the other side (unless you used a double handle).
* Create the new handle. The single handles come in left and right persuasions. A door needs a left facing handle on one side and a right facing handle on the other, so if you have already added the left handle create a right handle and line it up on the other side of the door.
* Name this handle. I prefer to keep a naming convention for each door and it's respective handles, it makes things alot easier. The door is named '''My_Door_1''', the first handle is named '''My_Handle_1''' so name the second handle '''My_Handle_1_1'''. This will make it stay with the first handle in the entity list. This is important to keep organized. If you name it My_Handle_2 then when you get to another door named My_Door_2 you'll be confused.
* Place and '''bind''' that handle to your door.

You now have two single door handles on either side of the door that rotate together as if they were physically attached.

'''To add a brush to a brush door''':
* Select the new brush ''and'' the brush door all together; ''the entity '''must''' be selected '''last'''.''
* Use {{menu|Edit|Reparent primitives}}. This ensures the parent entity adopts the new item(s).
* If you have trouble selecting them in the orthoview because other brushes, etc. get selected then try in the camera view or as a last resort move them temporarily to an open area (but keep them in the same positions relative to each other.) Use {{key-shift}}+{{LMB}} on new item(s) then {{key-shift}}+{{LMB}} on main entity. Once they are all selected, use the {{menu|Edit|Reparent primitives}}.

'''To add ''model'' static items''': knockers, hinges, static handles etc. to a ''Model Door'':
* Select item
* Right click in orthoview and select ''Create Entity'' then <code>entity func_static</code>
* Position it where you wish on your door.
* To synchronize this with your particular door you need to add the property ''bind'' and the individual door name to the brush entity. To do this...
** Select the model door.
** In the entity inspector, select the ''name'' line
** Select the bottom line in the input box ''below'' the properties window.
** Copy the name
** Deselect the door with {{key-esc}}
** Select the brush entity
** Add a property "bind" to it.
** Change the value of the property by pasting in the door name
** Click {{check}} or press {{key-enter}}

'''To add ''brush'' static items''': knockers, hinges, static handles to a Model Door:
* This method is not ideal but it seems to work OK.
* Select the brush.
* Right click in orthoview and select Create Entity then ''atdm:mover_door_handle''
* Position it where you wish on your door.

To synchronize this with your particular door you need to add the property ''door_handle'' on the door, and give as the value the name of the brush you just created.

This brush turns like a handle. To stop it:

* Adding ''rotate 0 0 0'' or disabling the handle script won't help.
* Add a real working handle (as in the section above ''To add a working model door handle...'' and it must be added LAST.)

If you don't want too see a real working handle added maybe try another tiny brush with the handle function and hide it inside the door?

===Locking Doors===

To lock a door check the ''show inherited properties'' in the entity inspector for a ''atdm:mover_door'' entity and you should see the ''locked'' property. Select it and in the input box below the properties you can change its value:

* 0 = unlocked (default)
* 1 = locked

If locked it will require an entity that is associated with it to be able to act as a key to unlock it.

Currently door handles on locked doors will rotate when frobbed, they will bounce back though and the door will stay locked until unlocked.

===Keys===

Assigning specific keys to specific doors is simple.

* It is recommended that you create an existing key entity. These keys have all required props, they just need to be named.

Alternatively you can create a key from the Model Viewer and want it to be useable
* Make sure it has the properties:
useable 1 [so it can be used by the door]
frobable 1
inv_name <unique name>
inv_category Keys
inv_target player1
inv_icon guis/assets/hud/inventory_icons/<icon name>
inv_stackable 0 or 1 where 1 can be used on all copies of the same key so they show as one entry in the inventory with a total.

Add to the door the property <code>used_by</code> with the name of the key as the value. Multiple keys can open the same door by using several <tt>used_by</tt> spawnargs:

"used_by" "doorkey_1"
"used_by1" "doorkey_2

==== Keys Carried by AI ====

So you have a door and you have a guard AI and you want the guard to be able to open/close/lock the door, but you also want the player to be able to pickpocket the key. Keys can be attached to AI in two ways.

''The Def_Attach Method''. This method is the best one for doors that you expect the AI to operate. It uses spawnargs to spawn the key at game start.

*"def_attach6" "atdm:prop_silverkey" // the entity to spawn - in this case a key.
*"pos_attach6" "belt_back_right" // where the key will spawn on the Ai.
*"name_attach6" "door_key" // this gives 'attach6' arg the name "door_key" and is the name the arg "used_by" will need, eg: "used_by" "door_key"
*"set inv_name on door_key" "Door key" // The name the key get when the play adds it to their inventory.
*"set name on door_key" "door_key" // here it gets a name to be used in the map in general.

For more info on this method, see [[Attaching Props to AI]].

''The Bind Method''. This lacks the animation finesse of def_attach, but does let you see the key in DR. The method is particularly helpful in, say, adding a second key to an AI in the back middle of a belt. The AI cannot use a bound key to open a locked door; the workaround is to fake it with "can_unlock" as discussed further below. Or to use bound keys mainly for items the AI will not attempt to open, such as hatches, duct covers, or chests.

* Load a key entity
* Position where you want it in relation to the AI, and bind it to them (i.e., "bind" "<AIname>")
* Add the spawnarg "bindToJoint" "Hips" (or another location like LeftHips_Dummy; see AI for list)
* Adjust existing spawnargs accordingly (that is, be sure the name and door's/chest's "used_by" match, if you aren't using a prefab chest with key). This is for the benefit of the player after pickpocketing the key; as stated above, the AI itself can't use it for unlocking.

For more info on this method, see [[Attaching_Items]] and [[BindToJoint]].

====Keys Carried by Player====

With a door's key selected in your inventory and the door highlighted, you can...
* unlock it (which will also auto-open if enabled) by either frobbing it or hitting the Use key (typically U or Enter).
* lock (or relock) it via the Use key. Why do this? To avoid pursuit, or to lure guards into a room, and then lock them in (if they don't have a key or specific can_unlock powers).

====Master Key for Testing====

By default, ALL locks can be opened by any key named ''key_master''. Just create a key in your map, name it ''key_master'' and it becomes a master key for use while testing. Add inv_map_start 1 to it so it is in the player inventory at game start. Remember to delete it when your mission is finished.

====Automatically Removing Keys from Player Inventory After Use====
If a fan mission has a lot of keys it can clog up the player inventory. If the key is single-use, it can be useful to automatically remove it from the player inventory after use. Below is a way to do it using a simple setup and a generic script function that can be used for multiple doors.

=====Generic Version=====

You'll need the following entities, preferably set up near each other in your map:
* The door entity itself
* A trigger_count entity
* An atdm:target_callscriptfunction entity
* some random entity for the target_callscriptfunction to target (explanation below)

The below diagram shows the spawnargs and targeting required for the setup:
[[File:Key remove2.png|left|thumb]]

<div style="clear: both"></div>
The script being called ('openDoor') is defined in fms/<mapname>/maps/<mapname>.script and looks like this:

void openDoor(entity target, entity door, entity callscriptfunction)
{
string keyName = door.getKey("used_by");
entity key = sys.getEntity(keyName);
$player1.replaceInvItem(key, $null_entity);
}

Explanation as follows:

'''For the door:'''
* '''trigger_on_open''' spawnarg: The door is configured to trigger its targets when it opens
* target '''trigger_count''' entity: this is the entity that is triggered when the door is opened
* '''used_by''' spawnarg: This names the key entity required for unlocking the door
* The other spawnargs are just the usual for setting the door as locked and unpickable

'''trigger_count entity:'''
* When triggered, this entity will in turn trigger the script that removes the key from the player inventory.
* '''count''' spawnarg: This is set to 1 because we only want the key removal script called once - the first time the player opens the door.
* this entity targets the atdm:target_callscriptfunction, which contains details of the script to execute

'''atdm:target_callscriptfunction entity:'''
* '''call''' spawnarg: This is the name of the script function to call
* '''foreach''' spawnarg: This version of the script event provides access to the 'activator', or the entity that triggered it (in this case, the door). Using that information we can obtain the key name. See [[A to Z Scripting: Ways of calling a script#target_callscriptfunction|here]] for details.
* '''target any static entity''': For this version of the script event to work, the target_callscriptfunction entity needs to target something. This can be any static entity in the map (i.e. one that won't get removed or anything). I usually just target the nearest entity (e.g. a light or a lamp, or a model). This provides no functionality in the context of this tutorial, it just satisfies the conditions of the script event.

'''The script:'''
* Pretty self-explanatory. The script gets the name of the key entity via the '''used_by''' spawnarg on the door, retrieves the key entity, and then replaces it in the player inventory with a null entity, effectively removing it.
* Any door can use this script as its generic (although they will need their own trigger_count entities. In theory they could share the same target_callscriptfunction entity, but that might become inconvenient - up to the mapper.

=====Simpler, No-script Version=====
This is similar to above, but is more limited. You need to hard-code the key name as a spawnarg on an atdm:target_itemremove entity as the key name can't be automatically determined like in the above script. This makes it slightly more error-prone as we're naming entities in more than one place, but ideal if you're uncomfortable with scripting.

[[File:Key remove4.png|left|thumb]]
<div style="clear: both"></div>

Explanation as follows:

'''atdm:target_itemremove entity:'''
* '''unique_item ''' spawnarg: The name of the key to remove from the player inventory

===Lockpicks===
''by Baddcog''

There are two lock pick types.
*'''s'''=snake
*'''t'''=triangular

A lock can be set with many pins. Each pin has a click sequence and each needs a designated lockpick type (see above). Keep in mind that the lockpicking in The Darkmod is much more involved than in T2 or T3. The player has to listen to sounds or watch a handle or lockbar to know when a lock is pin is picked.

This means that authors can be very evil and really frustrate the player, in which case their missions will probably not be played. So be nice to the player and don't waste your time. Use simple locks for the most part and save complicated locks for important sections and to build tension. Don't make the player have 20 pins to pick all with different lockpicks. In most cases 1 or 2 pins will suffice and it isn't necessary to use both lockpicks on every lock.
Also try to include a lock lever on lockboxes or chests, door handles will rotate as the pins are being picked. This gives the player visual clues to help with the picking (and essential in noisy environments where you can't hear the clicks.)
IMO this system is a huge leap foward for lockpicking but also has the ability to completely frustrate the player as stated above. Keep this in mind when designing your lockpick systems.

These props go on the door itself, or the lid of a chest, eg,
*'''lock_pins''' 1327
*'''lock_picktype''' stts

The lock_pins property specifies how many pins each lockpicktype has.
The lockpick_type property specifies how many times the player has to switch picks and which pick they have to use. You can see there must always be an equal number of lock_pins and lock_picktypes specified

So looking at the example above we have lockpick_type s(snake), t(triangular), t(triangular), and s(snake). The player will have to use these lockpicks in this order. Once the snake lockpick's pins are open the player can advance to the triangular pick and so forth.
5 is added to every click sequence so 5 is the minimum click pattern even if you set it to 0.
In the example above the lockpins specify in order which pick types have how many pins, so the s pick has 1 + 5 = 6 clicks, the t pick has 8 and so on.
The above is a difficult lock and to avoid annoying the player it is best only used rarely on a special lock like an important big vault door. Ordinary footlockers and common doors can be just 1 or 2 click sequences, eg, lock_pins 2 and lock_picktype t means the player uses one pick and listens for the end of one sequence of 7 clicks.

lockpick_rotate - is placed on the door. It is the amount the visible rotating handle or pin rotates while picking. For a rotating handle or lockbar normally ignore this and leave the default. During lockpicking it oscillates and progresses to the normal full turn of the handle. Example 0 45 0.

lockpick_translate - is placed on the door. It is the amount the visible handle or pin moves in a straight line while picking. Use this if you have eg, a lockbar that you want to move in a straight line and not rotate, eg sliding catch. Example 0 -5 0

By default, doors are pickable. If you don't set up the above lockpick spawnargs then it can't be picked. So there is normally no need to enable lockpicking - just set up the above spawnargs. There is a ''pickable'' spawnarg set to 1 by default. If set to 0 then the door becomes unpickable. But hard to think of an application except in testing or perhaps a special custom situation where it is switched by script perhaps.

===Open, Partially Open, or Closed Door at Game Start===

By default, doors are closed at game start. If you want a door to be already open or partially open then do the following.

'''Note well: Create all doors in their ''closed'' position. Adjust as follows and they will automatically be at the open position when game starts.'''

Already Open Rotating Door:
* Select the door.
* Select the entity inspector
* Check ''show inherited properties''
* Select the ''open'' property
* Edit the value to 1 in the input box below and tick the check button
* The door will now be fully open at game start.

* If you want it only partly open:
* Make sure its ''open'' property is set to 1 as above.
* Right click the entity inspector and select ''add property''
* Click the + sign on the left of the top line where atdm:mover_door is listed to open the folder. (if atdm:mover_door is not listed then the entity was likely changed from eg, func_static. If so, save the map and reload to update the add property list)
* scroll down, select ''start_rotate'' then click {{ok}}
* This adds it to the property list.
* Now select ''start_rotate'' in the property list.
* Edit the bottom line of the input box ''below'' the properties window to the angle you want in the same form as described in the ''Rotate Direction and Open Angle'' section. So for example, to have a door that has a fully open default ''rotate'' value of 0 90 0 to start only half open you would give it a ''start_rotate'' value of 0 45 0.
* In a similar way add the property ''first_frob_open".
* Set it to 1 and a partly open door should then open fully on the first frob.
* Set it to 0 and a partly open door should close on the first frob.

Already Open Sliding Door:
* Select the door.
* Select the entity inspector
* Check ''show inherited properties''
* Select the ''open'' property
* Edit the value to 1 in the input box below and click {{check}} or press {{key-enter}}
* The door will now be fully open at game start.

* If you want it only partly open:
* Right click the entity inspector and select ''add property''
* Make sure its ''open'' property is set to 1
* Click the + sign on the left of the top line where atdm:mover_door is listed to open the folder.
* scroll down, select ''start_position'' then click OK. (if atdm:mover_door is not listed then the entity was likely changed from eg, func_static. If so, save the map and reload to update the add property list)
* This adds it to the property list.
* Now select ''start_position'' in the property list.
* Edit the bottom line of the input box ''below'' the properties window to the position you want in the same form as described in the ''Sliding (Translation) Amount and Direction'' section. So for example, to have a door that has a fully open default ''translate'' value of 0 50 0 to start only half open you would give it a ''start_position'' value of 0 25 0.
* In a similar way add the property ''first_frob_open".
* Set it to 1 and a partly open door should then open fully on the first frob.
* Set it to 0 and a partly open door should close on the first frob.

===Rotation Centre, Pivot, Hinge point===

The centre of rotation of a door is at the origin point of its entity and the door rotates with reference to the orientation of that origin point, not the world map. See ''Rotate Direction...'' for more about that. This section only deals with the ''position'' of the rotation centre in the door.

Model Door Centre of Rotation:<br>
The centre of rotation of a model door cannot be changed within Dark Radiant. Because a model door rotates around the centre 'spine' of its back edge this will cause clipping (penetration into solid) as in this example (where the door is set to open to 89 degrees for clarity):<BR>[[Image:modelClipping.jpg]]<BR> So care is needed with placement. You will not normally position a door right next to a wall as in the example but against a shallow frame so clipping will barely be noticeable but either way it can be fixed. You can correct it by adding a translation (see ''Sliding (Translation) Directions'') value of half the door width in the direction of the door handle. This will gently move the door out as it rotates to clear any solid on that side as in this diagram:<br>
[[Image:DoorClip.jpg]]<br>
Half a door width will typically be about 2. Any 'attachments' such as door handles will still synchronize with the door movement whether the door is rotating, sliding, or both.

Brush Door Centre of Rotation:<br>
The centre of rotation of a brush door ''can'' be changed. The default origin point of a brush is at its centre. Therefore a default rotating brush door will rotate around its centre when you first create it. So, mappers will commonly need to move that rotation point to a corner or even to some other offset position for example, for an openable window using the door function.

Put simply, to move the rotation point of a brush door you need to move the entity origin relative to the brush(es.)

Moving the entity origin (centre of rotation) relative to a brush door:

* Select the brush door
* Select ''Vertices mode'' (default shortcut key is {{key|name=V}} or button on top toolbar 'Select Vertices')
* Drag the door's entity origin to the point where you want the door to rotate. This should be on the corner on the leading edge side (the side to where the door is opening.) to avoid clipping as in this diagram....
[[Image:getCorner.jpg]]
* You should now find that door rotates around that point.

===Rotate Direction and Open Angle===

By default, rotating doors open anti-clockwise (viewed from above) by 90 degrees from the start orientation. If you want to change this edit the ''rotate'' property in the entity inspector. Don't confuse this ''rotate'' property with the ''rotation'' property. In the entity inspector remember that to see the inherited rotate property you must check the box 'Show inherited properties'.

The three values shown in the rotate property are degrees from the closed position around Y Z X (absolute map axes Front, Top, Side views in DR's ortho view.)

* Positive Y = Open clockwise (Dark Radiant grid front view, looking north)
* Negative Y = Open anti-clockwise (Dark Radiant grid front view, looking north)

* Positive Z = Open anti-clockwise (Dark Radiant grid top view, looking down)
* Negative Z = Open clockwise (Dark Radiant grid top view, looking down)

* Positive X = Open anti-clockwise (Dark Radiant grid side view, looking west)
* Negative X = Open clockwise (Dark Radiant grid side view, looking west)

There is a problem when you come to rotations that are not around the main Y Z X axes of the map, for instance a drawbridge that lowers down to the south east. You might think you can combine Y Z X values to get the result you want - and this can be done (for south east use 45 45 90) but it is a bit of a kludge and the drawbridge twists eccentrically as it lowers (though it arrives correctly!)

The values are in the range -179 to +180. Positive values give an anti-clockwise opening rotation (looking down from above) and negative values give a clockwise opening rotation. The value 180 is unique in that it continues in an anti-clockwise rotation when closing rather than returning clockwise so might be used if you can think of some object that might need such a motion when frobbed!

Edit the rotate value by selecting it and using the input box at the bottom and clicking the check(tick) button. That will change the angle the door will open to. Note that the line with the original default of 0 90 0 will still be there but your new entry will be added on a separate line and that is the one that will work in the game. CAUTION: when adjusting later make sure you have your new line selected and not the original! If you do it will appear to change but your first setting will remain unaltered.

Examples:
* 0 90 0 = Opens anti-clockwise round the entity's 'vertical' to 90 degrees - typical default vertical door.
* 0 0 90 = Lowers a drawbridge from the entity 'vertical' to horizontal.
* 0 0 -45 = Opens clockwise by 45 degrees viewed from the east side. This might suit a skylight in a sloping roof.

'rotate' cannot be combined with translate motions (see [[#Sliding (Translation) Amount and Direction]]) in one door; you need to bind one door to another and link they by targetting one to the other. By that means you can produce exotic and useful motions. A door opening against an upward-sloping floor can thus have a ''lifting hinge'' and raise up slightly to clear the floor; a door can rotate towards you and slide back to one side very effectively.

===Sliding (Translation) Amount and Direction===

By default a Dark Mod door will rotate open. For most sliding doors you want to stop them rotating as well as make them slide. You cannot delete (remove) the ''rotate'' property - you have to set the ''rotate'' property to 0 0 0 to stop a door rotating (see ''Rotate Direction and Open Angle''.)

Now edit the ''translate'' property value by selecting it (remember to have inherited properties box checked) and using the input box at the bottom and clicking the check(tick) button. That will change the distance the door will slide to. Note that the line with the original default of 0 0 0 will still be there but your new entry will be added on a separate line and that is the one that will work in the game. CAUTION: when adjusting later make sure you have your new line selected and not the original! If you do it will appear to change but your first setting will remain unaltered.

Typically (but not always) you will want your sliding door to slide the width of the door. The three values in the translate property by default are 0 0 0 and are X Y Z ''absolute map'' values (irrespective of door orientation) where:

* Positive X = Slide East (Right side of Dark Radiant grid in top view)
* Negative X = Slide West (Left side of Dark Radiant grid in top view)
* Positive Y = Slide North (top of Dark Radiant grid in top view)
* Negative Y = Slide South (bottom of Dark Radiant grid in top view)
* Positive Z = Slide Up (Top of Dark Radiant grid in side views)
* Negative Z = Slide Down (Bottom of Dark Radiant grid in side views)

So for a 50 unit wide door you want to slide fully to the east you would use 50 0 0 for the translate property values. A 100 unit portcullis sliding vertically up would need 0 0 100 to be fully raised.

=== Doors Collision/Push Behaviour ===
Doors push all entities by default, except for the player. Doors will also stop moving when anything blocks their movement. However, this default behaviour can be changed by setting appropriate spawnargs:

Set '''push_player''' to '''1''' to let the player be pushed by this door:
"push_player" "1" // Push the player too (default is off)

By default '''stop_when_blocked''' is set to 1 and if a door is blocked by an entity then even if the entity is removed afterwards, the door stays where it is. The next frob will close the door.

Set '''stop_when_blocked''' to '''0''' to prevent the door from ending the opening sequence when anything blocks its way. It will still pause - but continue to open if the block is removed.
"stop_when_blocked" "0" // door keeps moving after being blocked (default is off)
With this setting, doors will still stop at blocking entities (the player, for instance), but will continue to move when the entity moves out of the way.

There is another spawnarg which stops a door pushing a moveable. Apply this to the ''moveable'', not the door...

"notPushable" "1"

===Door Sounds===

There are multiple ways to put sounds on doors.

''snd_open'' <br>
Sound is triggered as the door begins to open.

''snd_opened'' <br>
Sound is triggered when the door finishes opening. Defaults to "nosound".

''snd_move''<br>
The sound plays while the door moves. Defaults to "nosound".

''snd_close'' <br>
Sound is triggered as the door finishes closing.

The following sounds should be left on the default sound in most cases so players clearly know what is going on:

''snd_locked''<br>
The sound played when a player or an AI tries to open a locked door.

''snd_unlock string''<br>
The sound played when a door is unlocked.

You can silence any of these sounds by setting the following properties as shown:

''snd_open nosound''<br>
''snd_close nosound''

Don't just use a dash - as it seems to cause a sound of its own.

===Sound Propagation through Doors and Doorways===

''This information will change significantly with the release of 2.0. See'' [[Controlling Sound Loss Across Portals]]

The sound volume reduction to the player (ie, the sound the player hears) is fixed and constant in a cvar which adds a distance factor to the original sound. It is recommended that you do not change that because it will affect other FMs. Currently there is no way to change the way that sound to the player is reduced through doors and doorways.

Sound propagation to AI, eg, impact sounds or guard yells is treated separately:

Sound propagation to AI relies on visportals. For details study [[Sound Propagation: Part 1]] and [[Sound Propagation: Part 2]] as well as [[Visportals]] This tutorial will just cover the relevant sound and sound propagation ''properties'' of doors. If you set the ''show inherited properties'' box in the entity inspector you can see them as described here.

Remember, the following have no effect on what the player hears through a door or doorway.

''loss_open''<br>
Drop in sound volume in dB propagated to AI (not player) when going through an open door. (default 1dB)

''loss_closed''<br>
Drop in sound volume in dB propagated to AI (not player) when going through a closed door. (default 15dB) You would want to set this very high to block all sound with a thick door but very low for a barred gate for example.

''loss_double_open''<br>
Drop in sound volume in dB propagated to AI (not player) when going through double doors when only one is open. (default 1dB)

There are also various sound properties for lockpicking:<br>
''snd_lockpick_pin_1 through 14'' and ''snd_lockpick_pin_success''

===Allowing the Player to Interrupt Door Motion===

The door property ''interruptable'' determines whether a door can be stopped by frobbing while it is opening or closing. It is enabled (i.e., set to 1) by default. Then the player, by frobbing to start the normal opening, then frobbing again to interrupt, can open a door to any position, e.g., slightly ajar to peek through. Another frob will begin closing, and so on with any additional frobs to stop/reverse-direction.

Be aware that an rotating-style door, when left ajar, will subsequently open or close more slowly than normal in an angular-velocity sense. It instead takes the same time as a full (uninterrupted) opening or closing would take in seconds, as given by ''move_time'' discussed next.

===Speed of Door Opening and Closing===

Rotating Door Speed:<br>
The time a rotating door takes to open or close is set in the ''move_time'' property, no matter what its maximum open angle may be. So with rotation set at, say, 150 degrees the door just opens faster than at, say, 80 degrees. To change this value, make sure the door is selected then...

* Right click the entity inspector and check ''show inherited properties''
* Scroll down, select ''move_time''
* Edit the second line of the input box ''below'' the properties window to the time you want.
* The time is in seconds and decimal fractions can be used. The default is currently 1.75 seconds.

Sliding Door Speed:<br>
The speed of a sliding door is set in the ''translate_speed'' property. To add this, make sure the door is selected then...

* Right click the entity inspector and check ''show inherited properties''
* Scroll down, select ''translate_speed''
* Edit the second line of the input box ''below'' the properties window to the speed you want.
* The speed is in Dark Radiant grid units per second.
* The default is 0 and if set to this then the door slides open in one second whatever the distance, great or small.
* CAUTION: It is assumed ''translate'' has been changed from its default value of 0 0 0. If not, a non-zero ''translate_speed'' may cause problems.

===Visportals and Doors===

A visportal face surrounded by solid at its edges and in contact with a door is closed when the door is closed and enabled when the door is open. In most cases you will place a visportal in contact with a working door unless you can see through the door (such as a true glass door or barred gate*.) For full details see [[Visportals]].

''*As of 2.0 it is possible to make visportals that remain transparent when closed for gates and windows. See'' [[Controlling Sound Loss Across Portals]]

==Auto-Closing/Opening Doors==
Doors that automatically close after being open for some time are easy to setup: Each frobmover entity supports these spawnargs:

;"auto_close_time":Set this to something >= 0 to let the mover automatically close (again) after this time when being fully opened (measured in seconds). Defaults to -1, which means 'do not autoclose'. The event is also activated when the mover starts at the open position at map start.
;"auto_open_time":"Set this to something >= 0 to let the mover automatically open (again) after this time when being fully closed (measured in seconds). Defaults to -1, which means 'do not autoopen'. The event is also activated when the mover starts at the closed position at map start.

<div class="toccolours mw-collapsible mw-collapsed">
Before auto_close_time and the AI Door Management spawnargs next were provided, a more laborious method was used to auto-close doors as if AI were closing doors behind them. Hit "Expand" to review it.
<div class="mw-collapsible-content">I have one door that I particularly want the AI to close as there is a bit of frame lag inside if not. So I set this up and it works good as an auto-closing door - not as good as a true AI closing door as it will auto close when the player goes through as well but it does look very effective to see AI going through and closing the door behind them. Not tested exhaustively so I don't know if there could be any downside. Here's what to do....

First a quick summary to make it more clear:

'''''A trigger_relay is used both as a relay AND carries a stim. We put the trigger_relay with its stim in the path of the open door. The door has a response property. When it opens and contacts the stim its response is to send a signal back to the relay. The relay pauses then closes the door...'''''

* First, optionally give your door a suitable name like autodoor1, whatever.
* Copy that name to the clipboard.

Next we need a relay with a delay:

* Create entity > darkmod > trigger_relay

* Place it roughly at the position the door will be at when open and to be on the safe side 3/4th of the way to the far end of the door (not the hinge end) to give max distance from the close door.

* Add the property 'target' and paste in the door name you just copied.

* Give the relay itself a name, eg, autoDoor_relay_1, and copy that name to the clipboard, you'll need that too in a bit.

* Add the property delay and the value 3 - this is the delay in seconds before the door will close; 3 seems about right but 2 might be worth a try because to that 3 is added a random value between 0 to 0.5 seconds from the Time Interval we entered for the stim firings.

* Add the property 'wait' and the value 3. This is the time before it can work again in seconds. If you set it too low then in theory the door might trigger again but in this situation I don't think it's possible. Too long, eg, one minute, and it won't work if the AI goes back through the door before then. If this value is -1 then the whole thing will only work ONCE so might be used for an AI who goes through once, closes it behind him, but you don't want it to be an autodoor thereafter.

That's the relay, now we add a stim to it:

* Still with the trigger relay selected, go to {{menu|Entity|Stim/Response}}

* Custom stim tab.

* Click Add stim type, select the new custom stim type you just made at the bottom of the list and type in eg, autoDoorStim at top right in the input box.

* Click the stim tab and the little drop down arrow against the 'type' selector at bottom left and you should see your new custom stim name. Select it.

* Select the new autoDoorStim in the list and on the right you need only type in the radius box 15.0 There is quite a lot of room for error. I had it working on 10 and also on 25. The value should be less than the distance to the closed door else it will trigger open! But no so small that the door might not reach it.

* Select the check box for Time Interval and enter 500 (millisecs.) This is so it doesn't keep firing more frequently than is necessary. This stim will be firing all through your mission whether the door is used or not so if you had dozens of these then maybe it would affect performance. Too big a number and there may be a long delay before the door shuts - but it will be random depending on the next time the stim happens to fire. We'll control the delay we want more precisely later.

* Click {{ok}} to confirm it.

That's the stim set up, now for the response to it which is put on the door....

* Select the doorm, then use {{menu|Entity|Stim/response}} and select the response tab.

* Click the little drop down arrow against the 'type' selector at bottom left and you should see your new custom stim name. Select it.

* Right click in the big ''Response Effects'' box on the bottom right of the panel.

* Add New Effect and you should get a default 'Activate Response' response added to the list. Double click it.

* In the Effect selector at the stop select 'Trigger'

* in the Target box, paste in the name of the relay you copied or you can select it from the list at the little arrow.

* Leave the Activator box empty.

* Click {{apply}} and then {{ok}} on the main S & R panel bottom right.

It should now work. No need to wait for an AI, just frob the door and watch it close itself. If not, check the position of the stim brush is close to where the door stops when open.</div>
</div>

==AI Door management==

By default AI will open doors and close them behind them. Here are some spawnargs '''on the door''' the mapper can use to modify that behaviour:

;"ai_should_not_handle" :If set to 1, AI will not attempt to handle it and add it to the forbidden areas (so that it doesn't try to path through). They might still walk through the door when it is open though. Useful if you have some special use door that you don't want the AI to operate.

;"ai_should_not_close" :If set to 1, AI will not close the door behind them unless it obstructs them.

;"canRemainOpen" :If set to 1, it's the same as "ai_should_not_close, with the added behavior that this is ignored if the door needs to be relocked, or the door is marked "shouldBeClosed". '''(This spawnarg is available starting in TDM 2.02.)'''

Spawnargs '''on the AI''' that the mapper can use:

;"canCloseDoors" :Added in 2.12. Defaults to 1. If set to 0, the AI will not close doors after passing through them.

To get AI to unlock/relock specific doors there are two methods:

1. Provide the AI with the key, as detailed in the def_attach method in [[#Keys_carried_by_AI]] above.

2. Add the following spawnarg/value to the AI:

;"can_unlock" ''<doorname>''

For additional doors on the same AI use ''can_unlock1 doorname', `can_unlock2 doorname' etc. '''Do NOT use can_unlock_1.'''

If both (1) and (2) are used, then the AI can still go through the door after the player pickpockets the key. Otherwise, unless someone else opens the door for the AI, a typical sequence is that the AI checks their pockets for the missing key, stalls a bit at the locked door, and then (with now-better pathing algorithms) the AI uses an alternate route to the next path_corner, or "mentally" skips ahead in the route to next reachable node and goes there.

===Door Handling Positions===

It is also possible to set custom door handling positions for the AI. This is especially useful when the standard routine that lets the AI choose their standing positions while opening and closing the door fails, leaving them standing still, or circling around in front of the door helplessly.

Place a movers > ''atdm:door_handling_position'' entity where you want the AI to stand while opening/closing the door from this side.

On the door, you need to set the spawnarg "door_handle_position" "name_of_door_handling_position". You can also place a ''door_handling_position'' on each side of the door, and the AI will automatically choose the right one. In this case, you need to set spawnargs with "door_handle_position_1" etc., and the corresponding names of the ''door_handling_position'' entities on the door.

The ''door_handling_position'' entities can also carry spawnargs that define the behaviour of the AI, which are useful for example for doors that can only be opened or locked from one side:

'''"ai_no_open"''' If set to "1", the AI will not try to open the door from this side (but will still walk through when the door is already open).

'''"ai_no_close"''' If set to "1", the AI will not attempt to close the door from this side.

'''"ai_no_unlock"''' If set "1", the AI will not be able to unlock the door from this side, but still use it when it is not locked.

'''"ai_no_lock"''' If this is set "1", the AI will not lock the door from this side.

===Door Controllers===

'''Available in TDM 2.02+'''

You can design a door so it's operated by buttons or levers or switches (aka ''controllers'').

A controller is simply an entity that targets the door. Typical examples of entities that can be used are:

* Buttons: atdm:mover_button
* Levers: atdm:switch_rotate_lever
* Switch: atdm:mover_lever
* Lock: atdm:froblock. (See also next section)

1. Set up the door in the normal manner. It can be a rotating door, a sliding door, a locked door, etc.

2. Turn off the "frobable" spawnarg on the door. ("frobable" "0")

3. Create a controller entity on each side of the door. If you're setting up a locked door using atdm:froblock, there's no need to put any locking information on the controllers. When the game starts, it will transfer any locking information from the door to the controllers.

4. Give each controller the door as a target.

Both the player and any AI that wants to use the door will use the controllers to operate it. Any key, "can_unlock", or lockpick settings you would normally use at the door are now used at the controllers.

Controllers and ''door_handling_position'' entities can be used on the same door, but in that situation the ''door_handling_position'' entities don't define where the AI stands to operate the door. They simply provide the "ai_no_*" spawnargs that define AI behavior on each side of the door.

If you wish, you could provide a controller on only one side of the door instead of both sides. Note that, since the door is not frobable, the player won't be able to operate the door from the non-controller side.

====More about Using a Separate "Froblock" Lock Plate====
''by Geep, 2021-22''

Froblock, just discussed as a controller method, actually predated the controller concept in TDM. Here we recap that earlier context, with an alternative treatment of highlighting, and thoughts on texturing and usage.

Suppose you want to have a lock plate (typically mounted on a door frame or wall) that opens a nearby door, where the door and lock plate highlight separately. A traditional way is to adapt the ''froblock'' method described under the "Making your own" section of [[Containers, Chests, etc.]]

Basically, your door is the "chest lid" (of class atdm:mover_door) and your lock is the "chest body" (of class atdm:froblock). Set the properties as described in the wiki. There is a stock texture (darkmod/door/keyhole_metal_001) you can use to decorate a surface of your lock plate, or a patch on it. This method is probably most apt for small hatches and grates designed for the player alone, and with no handles, or non-turning handles attached with "bind".

===AI and 'non-frobable' Doors===
Be aware that the 'frobable' spawnarg only applies to the player, not AI. If you set a door to be non-frobable (i.e. 'frobable' '0'), AI can still operate it by interacting directly with it, even if it has a controller. For example they will do this if:

* they are fleeing or chasing the player
* the door has a controller but the AI can't reach it (for example the controller is on the other side of the door)

The best way to mitigate this is to use Door Handling Position entities (see above) with the 'ai_no_open' spawnarg set on them.

===AI locking doors behind them===

If one AI is involved (no one else is in the queue), he'll lock it behind him if he had to unlock it in the first place.

Prior to TDM 1.08, if more than one AI is using the door at the same time (there's a queue), the first AI unlocks the door, and the last AI through will only lock it if it's marked "should_always_be_locked" AND they have a "can_unlock" for that door or they have a key for that door. The last AI to use the door doesn't know that the first AI found it locked, because that info is kept per AI, and not per door.

Starting in TDM 1.08, if the first AI in a door queue found the door locked, that information is remembered by the door and the last AI through uses it to relock the door, as long as they have a "can_unlock" for that door or they have a key for that door.

In the rare case where a door is set up to use door-handling position entities (necessary for AI to use sliding doors), either or both of those entities can have the "ai_no_lock" spawnarg, which means AI aren't allowed to lock the door from that side.

==Initially Blocking a Door - Partially or Fully==
''by Geep 2021''

Suppose you have a door that you want to start out either as unopenable, or able to open just a crack, then later, after something happens, be fully openable and operational. One method known to work:

* Create a moveable object that the opening door runs into and tries to push.
* Arrange that the far side of the moveable object is jammed against some immovable worldspawn.

Here's two specific examples that use a wooden plank moveable:

* In "Perilous Refuge", a plank blocks the door leading out of the player's starting location, until the player carries it away.
* At the end of "Away0" (WIP 2021), the player tries to open a door. But if preconditions aren't met, the occupant seems to let the door open only a crack and complains. Blockage is done by an unseen plank resting on the floor hitting a knob of worldspawn. Preconditions met causes a "$plank.remove()" script call.

Other methods that you might think would work but don’t:

* Block with a func_static object, or an unjammed moveable with "notpushable 1" set. In both cases, the door travels through the object.
* In advance, "grab" an unjammed moveable to make it appear "solid" to the physics engine. (This was tested by having the player manipulate it; if it had worked, a “grabber” script call might suffice.)
* Dynamically change the door’s "rotate" limit from script using "setSpawnArg"; this function would only work before you spawn the door, not afterwards.

(Others possibilities not yet tested:

* Change "rotate" using the "setKey" script function; for some spawnargs this works even after spawn.
* Create a moveable and bind it to the world entity.
* If you are mainly interested in initially blocking an AI from using a door: it's possible that the AI re-reads the spawnargs for what doors it's allowed to open. Try adding a frob Response to the key (Entity -> Stim/Response... -> Response) with an effect that sets the “can_unlock" spawnarg on that AI to "-".)

==Controlling a Door by Scripting==
''by Geep 2021''
===If Unlocked===

Simply use, for example with a door named ''door1'':

$door1.Open();
...
$door1.Close();

Alternatively, toggle it open or closed with:

$door1.frob();

If the door has "interruptable 1" (which is the default with atdm:mover_door), you can also frob() it twice to leave it ajar. Interpose and adjust a sys.wait(...) to tune it.
===If Locked===

You need to unlock it first. Changing the door's "locked" spawnarg value won't work. Instead you will use:

$door1.Unlock();

But there are complications. By default, the door has spawnarg "open_on_unlock 1". So, assuming you didn't change that, you'd think unlocking the door would open it. But this spawnarg will be ignored if the gamer has global menu option "Open Doors on Unlock" set to Off. Assuming you want to reliably have the door open, do this:

$door1.Unlock(); // MAYBE will open door too.
sys.wait(3); // If so, wait for door to fully open. Value may need adjusting based on door's speed
$door1.Open(); // Otherwise, open it now.

The wait is added, because otherwise, the opening begun by Unlock may be stopped by Open with the door only partially open. (Probably an alternative to using sys.wait here is to zero the door's "interruptable" spawnarg.)

==Doors as Triggers==

''by Ishtvan & greebo''

Doors (or any binary frob mover, buttons, levers, etc) now have the option to [[Triggers|trigger]] their target on closing or opening. (For definition purposes, a button is defined as "closed" in the state when it starts out and "open" in the state you press it down to. I know that's a little non-intuitive, but it came from deriving from doors).

New spawnargs on frob movers:
;"trigger_on_open" :If set to 1, this binary mover will trigger its targets when it starts out completely closed and is opened.
;"trigger_when_opened":If set to 1, this binary mover will trigger its targets when it is completely opened. Code defaults to 0.
;"trigger_on_close":If set to 1, this binary mover will trigger its targets when it completely closes after being open.

== Suspicious Doors ==

If you give a door the spawnarg '''"shouldBeClosed" "1"''', then AI will treat it as suspicious if they find the door open.

Doors with that spawnarg should work like this:

- an AI opening the door knows he's not to become suspicious if he opened the door

- nearby AI alerted by the open door will also not react if they can see the door, and can see the AI that opened it

- AI who come upon the open door later probably won't be able to see the AI that opened it, so they'll treat it as suspicious

- if the AI who opened the door comes upon the door later, and it's still open, and no one's touched it since he opened it, he'll see his name on the door and won't become suspicious. "Oh, crap. I forgot to close it earlier."

- If an AI comes upon an open door that should be closed, he should close it whether he becomes suspicious or not.

'''Post TDM 2.00:'''
- AI turn to look at a door they see opening. The player can crack open a suspicious door to peek out w/o grabbing the attention of a nearby AI. After 5s, the AI will notice the cracked open door. Non-suspicious doors can be cracked open indefinitely w/o nearby AI noticing.

==Slanted or Tilted Doors==
Slanted or tilted doors can be made as follows:

1) Place your door, preferrably one of the prefab doors, which have a model door and model handle and all the rotation spawnargs pre-set.

2) rotate and place the door+handle model into place you want it to be. Now, if you use the door in the game, the door will rotate around the world z-axis, and not the door model z-axis (which is rotated).

3) to get the door to rotate around the door model z-axis, you must place a model (any model will do, and it can be placed anywhere in the map). Rotate the new model into the same orientation your door model was rotated, i.e. if you door is rotated 45 degrees around the x-axis, do the same rotation on the new model.

4) bind the doors on the new model. This makes the doors start rotating along the new model origin (which is rotated the same way as the doors).

5) working slanted door.

Do note, that all the rotated objects need to be models (suspicion, not tested). You can export DR built stuff into a model using the DR ase exporter script. For custom doors, remember that the exporter places the model origin at the map origin if you do not choose the "place origin in the middle of the object" option.

Also note that the AI probably cannot use slanted doors and might get stuck (suspicion, not tested).

There is a link to a test map here:
http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/?p=395486

==Skins: A Wide Variety of Door Textures==

This is to remind you that as with many Dark Mod models, there is a wide range of extras skins (textures) available for door models. There are now several basic door entities of different sizes so choose your size first. Then enter the spawnarg: skin with any temporary value. Now select it and click the skin button at the bottom of Dark Radiant's Entity Inspector and you will find a large of range of skin textures from which to select to give you a choice of appearances for your door.

==Extra Notes==

''func_darkmod_door'' is no longer used (just in case you come across it in the Dark Mod forums or wiki.) '''<code>atdm:mover_door</code>''' is the entity to use.

{{tutorial-editing}}

Doors

2025-11-06T20:05:41Z

Frost Salamander: /* Simpler, No-script Version */

{{todo}}
''Written by Fidcal'' ''edit Baddcog''

==Quick Summary==

Quick way to get an unlocked door in your map:

* Insert one of the prefab doors complete with handles and select its skin property and click the button to change its skin appearance to whatever you want. Set any other properties you need.

Alternatively,

* Create a door from the entity list
* Use the "skin" spawnarg on the door to change its appearance.
* Create a handle from the entity list
* Add the ''door_handle'' property to the door and give it the name of the handle
* To the door handle add the value frob_peer and use the name of the door.
* To open clockwise, change the ''rotate'' property from <code>0 90 0</code> to <code>0 -90 0</code>

==Introduction==

This tutorial explains how to put doors into your map using Dark Radiant, as well as adjust them and their properties.

The rest of this tutorial assumes that you have a basic understanding of using DarkRadiant. If you haven't done so, please go read the [[Dark Radiant Must Know Basic Intro]] article first.

Additionally:

* Up, down, right, and left in Dark Radiant's ''top'' orthoview are regarded here as the standard map directions of North, South, East, and West where useful for clarity.
* Where the term ''brush'' is used with a door it mostly also applies to a door made up of a group of brushes and/or patches.
* Where the term ''door'' is used it often will also apply to any object you wish to rotate when frobbed, for instance an openable window, box lid, or even more exotic objects that the imaginative mapper might conceive like a signal, engine part, toy, or whatever. So long as it needs to turn or slide just a fixed amount when frobbed then return when frobbed again then the following applies.

==Door types==

All tangible objects in Dark Mod are ''entities'', having either a pre-made model shape or else brush/patch(es). So there are two ways to create a door in Dark Radiant: as a model door or a textured brush door (or a hybrid of the two).

Models are ready made door objects but cannot within Dark Radiant (at the time of writing) be resized, rescaled, cropped or clipped whereas brushes are very flexible in that respect and can be worked into custom shapes for your map, including secret doors that blend into walls and other surfaces.

Most of the current door models are found in two places along with the door handles.
*Model Viewer: doors created from here will be static in the world and have no props other than material type.
You can add any props to them to make them working doors. If nothing else it is a good place to view the different size and skin options for the doors.
*Entity List: most of the door models can be found here. These doors have properties already assigned so they are ready to be used. Only one base door of each type is listed, create the size/hinge count door you want (2 hinge doors have a 'no hinge' skin). You can choose a skin for the door once it has been created in the editor with the "skin" spawnarg (use the model name of the door you want, taken from the model list, as its value). This is the easiest way to create a door. The same goes for door handles.

Remember also that door functions may be applied to objects other than doors, such as openable windows, drawbridges, gates, etc. In fact, anything that needs a partial rotation or slide when frobbed then return when frobbed again, such as a signal device. Lockboxes and chests use similar properties.

You can create one door/handle set and copy/paste it, but you need to take great care that all the name props are changed to match in each clone. Otherwise you get handles that fly off when a distant door moves, and handles that don't move.

==Creating a Door==

Put simply, to make a door you will be creating an 'entity with model' or 'entity with brush' or some variation thereof.

===Creating a Model Door===

There are several approaches to making a model door; the simplest is to create a door from the entity list; or create a door from the model viewer (good for static unusable prop doors).

'''Entity List''':

*Deselect everything in editor by hitting the Esc button
*Right-click an ortho view and select Create Entity
*Navigate to darkmod/movers/''atdm:door_...'', choose the door you want
*Click Add
*To change its appearance, add a "skin" spawnarg to the door, with the value being the model name of the door you want.

You now have a workable door in your level.

'''Model Viewer''':

* Right click in the orthoview, select ''Create Model'' then <code>darkmod</code> and select a door.
* Note that you can left drag the image in the ''Choose Model'' dialog to rotate it around.
* Click [[Image:Button ok.png]] and you have a static door.
* If you want to make it work (openable, frobbable) then:
** Select the entity inspector,
** Select the top classname line so it highlights
** Select the func_static line in the input box ''below'' the properties window.
** Edit <code>func_static</code> to <code>atdm:mover_door</code>
** Click {{check}} or press {{key-enter}}

Alternatively you can do it the old way:

* Create any temporary brush
* Right click in orthoview and select <code>Create Entity</code> then <code>atdm:mover_door</code>.
* Left lick the model name line in the entity inspector.
* Below it on the ''Entity Inspector'' panel you should now see a button 'Choose Model'
* Left click it, select a door model from the darkmod group.
* Note that you can left drag the image in the ''Choose Model'' dialog to rotate it around.
* The temporary brush was deleted.

In all three instances, you now have a working door with default properties.

Name your door by adding the prop (or modifing it) to name ''My_Door_1''. You can use any name that you feel is appropriate but all doors with handles attached ''must'' have their own specific name. Use the name My_Door_1 for your first attempt as it will be referenced when you get around to attaching handles (see below).

To add a handle and other adjustments, see [[#Customising and Adjusting Door Properties]] below.

===Creating a Textured Brush Door===

'''Tip:''' If unsure of size then you might insert a temporary human AI first to get a sense of height.

==== The simplest brush door: ====

* Drag out a new brush to the size required, eg, a seven foot high door is 84" x 1.1 = about 90 units in Dark Radiant.
* Give it a door texture from the texture browser (or wall texture for a secret door)
* Right click in orthoview and select ''Create Entity'' then <code>atdm:mover_door</code>

You now have a working door but it will rotate around its center. To move the rotation point to where you want the door hinges to be:
* Select the door and press 'v' or the ''Select Vertices'' button to enter vertex editing mode. The door's origin will show up as a small green square in the middle of the brush.
* In top-down orthoview, move the origin from the center to the corner of the brush. This is easiest in drag mode ('q' or the ''Resize'' button), although you can use translate mode ('w' or the ''Translate'' button) by manually selecting the vertex first.

==== Multi-brush doors: ====

More complex multi-brush doors can be created using the [[Clipper]] tool, CSG, etc. - this is not covered in this tutorial. Then assign <code>atdm:mover_door</code> for that whole brush structure. Also you can collect various brushes positioned together in relation to one another as needed, select them all, then assign <code>atdm:mover_door</code> for the group. All the brushes will be children of the <code>atdm:mover_door</code> entity and will rotate and be frobbable, etc. as one unit, as one door. To add further brushes or even model shapes later see the section on [[#Adding handles and other items to doors]].

Name your door by adding the prop (or modifing it) to name My_Door_1. You can use any name that you feel is appropriate but all doors with handles attached must have their own specific name. Use the name My_Door_1 for your first attempt as it will be referenced when you get around to attaching handles (see below). (repeated from above in case you didn't choose to create a model door)

=== Double Doors ===
Double doors are automatically recognised by the code when the doors are spawned. The prerequisite is that both doors are sharing/touching the same visportal. The spawnarg ''auto_setup_double_door'' (which defaults to "1") will take care of setting up the open/lock peer relationship between the two doors. The doors will open/close and lock/unlock along with each other as a result.

What happens behind the scenes: the doors are adding each other to their internal open_peer and lock_peer list, which causes the double doors to perform the same action when frobbed or used.

Note that ''auto_setup_double_door'' will not set the frob_peer relationship, i.e. each door will frob-highlight on its own without highlighting the other door. You'll need to add that spawnarg manually if you want to highlight the entire double door as one.

==Customising and Adjusting Door Properties==

Handles, lockplates, etc. can be added to doors and door properties can be adjusted for rotation, sliding, locking, and more.

Some of the door models have hinge plates and lockboxes that are reskinnable with a good variety of skins.

===Door handles and other door attachments===

'''Summary: just add the property ''bind'' with the door's name to the attachment and position it where you want it on the door. If it's a ''atdm:mover_door_handle'' then it automatically will work as a handle but you can bind virtually anything.'''
You can add handles and other items to doors such that they move correctly with the door whether rotating, sliding, or both and even if the door is not vertical such as a skylight or trapdoor.
Handle models come in two types, ''single handles'' and ''double handles''. A single handle is one sided, this means the handle will be inside the door or outside the door, but not both. A double handle has a lever on the inside of the door and a handle on the outside of the door. Each has benefits.

*'''''Single door handles''''':
Single door handles can be used on a static door, a door that's just for show that no AI's or the player can use. In this case you should just create a door handle from the model viewer, it will be static and have no properties such as scripts. It is for looks only. Note that TDM is trying to establish the expectation that decorative doors that cannot be opened do not have handles (though not all maps follow this).

I will call this ''multiple handles'', see more below.

These can also be useful on brush doors created in the editor that may be very thin or very wide.

*'''''Double door handles''''':
These are models have have a handle inside and outside. The bonus is that they only use one entity. Maps are limited to about 4,000 entities but when you count lights, AI, sound speakers, ect... you can run out of entities quickly on a large map. If you plan on building a large map this is the way to go, even in a small map they have benefits, namely that you only have to attach one handle per door.

Whether you decide to use a single handle or a double handle you must first follow the instructions below and attach one handle first. If you choose a double handle, follow the instructions below and you are done. If you choose a single handle type follow the instructions then also follow the ''multiple handle'' instructions for the second handle.

Both single and double handle types can be found in two places. The model viewer which will create a static model good for show, you can manually add props to make them work OR you can look in the entity browser.
Using a handle from the entity browser saves you a little bit of time as some props are already added, you just need to add the frob_peer names for the doors/handles and the door_handle name to the door.

=== Adding a working model door handle===

Quick summary:
* Create a model or brush handle and make it an ''atdm:mover_door_handle'' entity.
* Position it on your door. Use the opposite side from the door's multicolor X-Y-Z indicator (highlight the door to see it) if it's not obvious which side it goes on.
* '''Bind''' the handle to the door (bind <doorname>)
* It should now be a working handle though may need adjustments of rotation etc. see later.

Important: read preceding section on door handle types and performance issues first.

This works with both a model door and a brush door:

'''Rotation''':
* By default the door handle entity rotates ''anti-clockwise'' (looked at from the front) then springs back. A ''double handle'' model is OK but two singles (see ''Multiple door handles'' below) need more care as only one is the functioning entity and the other is just attached to it. So anti-clockwise is fine for a door with its hinge on the left and the handle on the right - the handle will rotate down then spring back. If you put the functioning door handle on the other side you will have to change the default ''rotate'' property from -45 0 0 to 45 0 0. '''''Therefore it is easier to generally put this handle on the side of the door where the hinge is on the left and the non-functioning attachment handle on the other side.'''''
*If your door only needs one handle, eg, a cupboard door, and from outside its hinge is on the right then you will need to change the ''rotate'' property of the handle as described above.

'''''The functioning handle entity:'''''
* Create an entity door handle (movers folder) or create a brush or model handle and assign it the entity ''atdm:mover_door_handle''.
* Position it where you wish on your door.
* '''Bind''' the handle to the door, by adding the "bind" spawnarg to the handle.

You now have a working door handle with default properties.

*'''Multiple door handles''':
Now that you've got a handle attached to one side of the door it is time to add one to the other side (unless you used a double handle).
* Create the new handle. The single handles come in left and right persuasions. A door needs a left facing handle on one side and a right facing handle on the other, so if you have already added the left handle create a right handle and line it up on the other side of the door.
* Name this handle. I prefer to keep a naming convention for each door and it's respective handles, it makes things alot easier. The door is named '''My_Door_1''', the first handle is named '''My_Handle_1''' so name the second handle '''My_Handle_1_1'''. This will make it stay with the first handle in the entity list. This is important to keep organized. If you name it My_Handle_2 then when you get to another door named My_Door_2 you'll be confused.
* Place and '''bind''' that handle to your door.

You now have two single door handles on either side of the door that rotate together as if they were physically attached.

'''To add a brush to a brush door''':
* Select the new brush ''and'' the brush door all together; ''the entity '''must''' be selected '''last'''.''
* Use {{menu|Edit|Reparent primitives}}. This ensures the parent entity adopts the new item(s).
* If you have trouble selecting them in the orthoview because other brushes, etc. get selected then try in the camera view or as a last resort move them temporarily to an open area (but keep them in the same positions relative to each other.) Use {{key-shift}}+{{LMB}} on new item(s) then {{key-shift}}+{{LMB}} on main entity. Once they are all selected, use the {{menu|Edit|Reparent primitives}}.

'''To add ''model'' static items''': knockers, hinges, static handles etc. to a ''Model Door'':
* Select item
* Right click in orthoview and select ''Create Entity'' then <code>entity func_static</code>
* Position it where you wish on your door.
* To synchronize this with your particular door you need to add the property ''bind'' and the individual door name to the brush entity. To do this...
** Select the model door.
** In the entity inspector, select the ''name'' line
** Select the bottom line in the input box ''below'' the properties window.
** Copy the name
** Deselect the door with {{key-esc}}
** Select the brush entity
** Add a property "bind" to it.
** Change the value of the property by pasting in the door name
** Click {{check}} or press {{key-enter}}

'''To add ''brush'' static items''': knockers, hinges, static handles to a Model Door:
* This method is not ideal but it seems to work OK.
* Select the brush.
* Right click in orthoview and select Create Entity then ''atdm:mover_door_handle''
* Position it where you wish on your door.

To synchronize this with your particular door you need to add the property ''door_handle'' on the door, and give as the value the name of the brush you just created.

This brush turns like a handle. To stop it:

* Adding ''rotate 0 0 0'' or disabling the handle script won't help.
* Add a real working handle (as in the section above ''To add a working model door handle...'' and it must be added LAST.)

If you don't want too see a real working handle added maybe try another tiny brush with the handle function and hide it inside the door?

===Locking Doors===

To lock a door check the ''show inherited properties'' in the entity inspector for a ''atdm:mover_door'' entity and you should see the ''locked'' property. Select it and in the input box below the properties you can change its value:

* 0 = unlocked (default)
* 1 = locked

If locked it will require an entity that is associated with it to be able to act as a key to unlock it.

Currently door handles on locked doors will rotate when frobbed, they will bounce back though and the door will stay locked until unlocked.

===Keys===

Assigning specific keys to specific doors is simple.

* It is recommended that you create an existing key entity. These keys have all required props, they just need to be named.

Alternatively you can create a key from the Model Viewer and want it to be useable
* Make sure it has the properties:
useable 1 [so it can be used by the door]
frobable 1
inv_name <unique name>
inv_category Keys
inv_target player1
inv_icon guis/assets/hud/inventory_icons/<icon name>
inv_stackable 0 or 1 where 1 can be used on all copies of the same key so they show as one entry in the inventory with a total.

Add to the door the property <code>used_by</code> with the name of the key as the value. Multiple keys can open the same door by using several <tt>used_by</tt> spawnargs:

"used_by" "doorkey_1"
"used_by1" "doorkey_2

==== Keys Carried by AI ====

So you have a door and you have a guard AI and you want the guard to be able to open/close/lock the door, but you also want the player to be able to pickpocket the key. Keys can be attached to AI in two ways.

''The Def_Attach Method''. This method is the best one for doors that you expect the AI to operate. It uses spawnargs to spawn the key at game start.

*"def_attach6" "atdm:prop_silverkey" // the entity to spawn - in this case a key.
*"pos_attach6" "belt_back_right" // where the key will spawn on the Ai.
*"name_attach6" "door_key" // this gives 'attach6' arg the name "door_key" and is the name the arg "used_by" will need, eg: "used_by" "door_key"
*"set inv_name on door_key" "Door key" // The name the key get when the play adds it to their inventory.
*"set name on door_key" "door_key" // here it gets a name to be used in the map in general.

For more info on this method, see [[Attaching Props to AI]].

''The Bind Method''. This lacks the animation finesse of def_attach, but does let you see the key in DR. The method is particularly helpful in, say, adding a second key to an AI in the back middle of a belt. The AI cannot use a bound key to open a locked door; the workaround is to fake it with "can_unlock" as discussed further below. Or to use bound keys mainly for items the AI will not attempt to open, such as hatches, duct covers, or chests.

* Load a key entity
* Position where you want it in relation to the AI, and bind it to them (i.e., "bind" "<AIname>")
* Add the spawnarg "bindToJoint" "Hips" (or another location like LeftHips_Dummy; see AI for list)
* Adjust existing spawnargs accordingly (that is, be sure the name and door's/chest's "used_by" match, if you aren't using a prefab chest with key). This is for the benefit of the player after pickpocketing the key; as stated above, the AI itself can't use it for unlocking.

For more info on this method, see [[Attaching_Items]] and [[BindToJoint]].

====Keys Carried by Player====

With a door's key selected in your inventory and the door highlighted, you can...
* unlock it (which will also auto-open if enabled) by either frobbing it or hitting the Use key (typically U or Enter).
* lock (or relock) it via the Use key. Why do this? To avoid pursuit, or to lure guards into a room, and then lock them in (if they don't have a key or specific can_unlock powers).

====Master Key for Testing====

By default, ALL locks can be opened by any key named ''key_master''. Just create a key in your map, name it ''key_master'' and it becomes a master key for use while testing. Add inv_map_start 1 to it so it is in the player inventory at game start. Remember to delete it when your mission is finished.

====Automatically Removing Keys from Player Inventory After Use====
If a fan mission has a lot of keys it can clog up the player inventory. If the key is single-use, it can be useful to automatically remove it from the player inventory after use. Below is a way to do it using a simple setup and a generic script function that can be used for multiple doors.

=====Generic Version=====

You'll need the following entities, preferably set up near each other in your map:
* The door entity itself
* A trigger_count entity
* An atdm:target_callscriptfunction entity
* some random entity for the target_callscriptfunction to target (explanation below)

The below diagram shows the spawnargs and targeting required for the setup:
[[File:Key remove2.png|left|thumb]]

<div style="clear: both"></div>
The script being called ('openDoor') is defined in fms/<mapname>/maps/<mapname>.script and looks like this:

void openDoor(entity target, entity door, entity callscriptfunction)
{
string keyName = door.getKey("used_by");
entity key = sys.getEntity(keyName);
$player1.replaceInvItem(key, $null_entity);
}

Explanation as follows:

'''For the door:'''
* '''trigger_on_open''' spawnarg: The door is configured to trigger its targets when it opens
* target '''trigger_count''' entity: this is the entity that is triggered when the door is opened
* '''used_by''' spawnarg: This names the key entity required for unlocking the door
* The other spawnargs are just the usual for setting the door as locked and unpickable

'''trigger_count entity:'''
* When triggered, this entity will in turn trigger the script that removes the key from the player inventory.
* '''count''' spawnarg: This is set to 1 because we only want the key removal script called once - the first time the player opens the door.
* this entity targets the atdm:target_callscriptfunction, which contains details of the script to execute

'''atdm:target_callscriptfunction entity:'''
* '''call''' spawnarg: This is the name of the script function to call
* '''foreach''' spawnarg: This version of the script event provides access to the 'activator', or the entity that triggered it (in this case, the door). Using that information we can obtain the key name. See [[A to Z Scripting: Ways of calling a script#target_callscriptfunction|here]] for details.
* '''target any static entity''': For this version of the script event to work, the target_callscriptfunction entity needs to target something. This can be any static entity in the map (i.e. one that won't get removed or anything). I usually just target the nearest entity (e.g. a light or a lamp, or a model). This provides no functionality in the context of this tutorial, it just satisfies the conditions of the script event.

'''The script:'''
* Pretty self-explanatory. The script gets the name of the key entity via the '''used_by''' spawnarg on the door, retrieves the key entity, and then replaces it in the player inventory with a null entity, effectively removing it.
* Any door can use this script as its generic (although they will need their own trigger_count and target_callscriptfunction entities)

=====Simpler, No-script Version=====
This is similar to above, but is more limited. You need to hard-code the key name as a spawnarg on an atdm:target_itemremove entity as the key name can't be automatically determined like in the above script. This makes it slightly more error-prone as we're naming entities in more than one place, but ideal if you're uncomfortable with scripting.

[[File:Key remove4.png|left|thumb]]
<div style="clear: both"></div>

Explanation as follows:

'''atdm:target_itemremove entity:'''
* '''unique_item ''' spawnarg: The name of the key to remove from the player inventory

===Lockpicks===
''by Baddcog''

There are two lock pick types.
*'''s'''=snake
*'''t'''=triangular

A lock can be set with many pins. Each pin has a click sequence and each needs a designated lockpick type (see above). Keep in mind that the lockpicking in The Darkmod is much more involved than in T2 or T3. The player has to listen to sounds or watch a handle or lockbar to know when a lock is pin is picked.

This means that authors can be very evil and really frustrate the player, in which case their missions will probably not be played. So be nice to the player and don't waste your time. Use simple locks for the most part and save complicated locks for important sections and to build tension. Don't make the player have 20 pins to pick all with different lockpicks. In most cases 1 or 2 pins will suffice and it isn't necessary to use both lockpicks on every lock.
Also try to include a lock lever on lockboxes or chests, door handles will rotate as the pins are being picked. This gives the player visual clues to help with the picking (and essential in noisy environments where you can't hear the clicks.)
IMO this system is a huge leap foward for lockpicking but also has the ability to completely frustrate the player as stated above. Keep this in mind when designing your lockpick systems.

These props go on the door itself, or the lid of a chest, eg,
*'''lock_pins''' 1327
*'''lock_picktype''' stts

The lock_pins property specifies how many pins each lockpicktype has.
The lockpick_type property specifies how many times the player has to switch picks and which pick they have to use. You can see there must always be an equal number of lock_pins and lock_picktypes specified

So looking at the example above we have lockpick_type s(snake), t(triangular), t(triangular), and s(snake). The player will have to use these lockpicks in this order. Once the snake lockpick's pins are open the player can advance to the triangular pick and so forth.
5 is added to every click sequence so 5 is the minimum click pattern even if you set it to 0.
In the example above the lockpins specify in order which pick types have how many pins, so the s pick has 1 + 5 = 6 clicks, the t pick has 8 and so on.
The above is a difficult lock and to avoid annoying the player it is best only used rarely on a special lock like an important big vault door. Ordinary footlockers and common doors can be just 1 or 2 click sequences, eg, lock_pins 2 and lock_picktype t means the player uses one pick and listens for the end of one sequence of 7 clicks.

lockpick_rotate - is placed on the door. It is the amount the visible rotating handle or pin rotates while picking. For a rotating handle or lockbar normally ignore this and leave the default. During lockpicking it oscillates and progresses to the normal full turn of the handle. Example 0 45 0.

lockpick_translate - is placed on the door. It is the amount the visible handle or pin moves in a straight line while picking. Use this if you have eg, a lockbar that you want to move in a straight line and not rotate, eg sliding catch. Example 0 -5 0

By default, doors are pickable. If you don't set up the above lockpick spawnargs then it can't be picked. So there is normally no need to enable lockpicking - just set up the above spawnargs. There is a ''pickable'' spawnarg set to 1 by default. If set to 0 then the door becomes unpickable. But hard to think of an application except in testing or perhaps a special custom situation where it is switched by script perhaps.

===Open, Partially Open, or Closed Door at Game Start===

By default, doors are closed at game start. If you want a door to be already open or partially open then do the following.

'''Note well: Create all doors in their ''closed'' position. Adjust as follows and they will automatically be at the open position when game starts.'''

Already Open Rotating Door:
* Select the door.
* Select the entity inspector
* Check ''show inherited properties''
* Select the ''open'' property
* Edit the value to 1 in the input box below and tick the check button
* The door will now be fully open at game start.

* If you want it only partly open:
* Make sure its ''open'' property is set to 1 as above.
* Right click the entity inspector and select ''add property''
* Click the + sign on the left of the top line where atdm:mover_door is listed to open the folder. (if atdm:mover_door is not listed then the entity was likely changed from eg, func_static. If so, save the map and reload to update the add property list)
* scroll down, select ''start_rotate'' then click {{ok}}
* This adds it to the property list.
* Now select ''start_rotate'' in the property list.
* Edit the bottom line of the input box ''below'' the properties window to the angle you want in the same form as described in the ''Rotate Direction and Open Angle'' section. So for example, to have a door that has a fully open default ''rotate'' value of 0 90 0 to start only half open you would give it a ''start_rotate'' value of 0 45 0.
* In a similar way add the property ''first_frob_open".
* Set it to 1 and a partly open door should then open fully on the first frob.
* Set it to 0 and a partly open door should close on the first frob.

Already Open Sliding Door:
* Select the door.
* Select the entity inspector
* Check ''show inherited properties''
* Select the ''open'' property
* Edit the value to 1 in the input box below and click {{check}} or press {{key-enter}}
* The door will now be fully open at game start.

* If you want it only partly open:
* Right click the entity inspector and select ''add property''
* Make sure its ''open'' property is set to 1
* Click the + sign on the left of the top line where atdm:mover_door is listed to open the folder.
* scroll down, select ''start_position'' then click OK. (if atdm:mover_door is not listed then the entity was likely changed from eg, func_static. If so, save the map and reload to update the add property list)
* This adds it to the property list.
* Now select ''start_position'' in the property list.
* Edit the bottom line of the input box ''below'' the properties window to the position you want in the same form as described in the ''Sliding (Translation) Amount and Direction'' section. So for example, to have a door that has a fully open default ''translate'' value of 0 50 0 to start only half open you would give it a ''start_position'' value of 0 25 0.
* In a similar way add the property ''first_frob_open".
* Set it to 1 and a partly open door should then open fully on the first frob.
* Set it to 0 and a partly open door should close on the first frob.

===Rotation Centre, Pivot, Hinge point===

The centre of rotation of a door is at the origin point of its entity and the door rotates with reference to the orientation of that origin point, not the world map. See ''Rotate Direction...'' for more about that. This section only deals with the ''position'' of the rotation centre in the door.

Model Door Centre of Rotation:<br>
The centre of rotation of a model door cannot be changed within Dark Radiant. Because a model door rotates around the centre 'spine' of its back edge this will cause clipping (penetration into solid) as in this example (where the door is set to open to 89 degrees for clarity):<BR>[[Image:modelClipping.jpg]]<BR> So care is needed with placement. You will not normally position a door right next to a wall as in the example but against a shallow frame so clipping will barely be noticeable but either way it can be fixed. You can correct it by adding a translation (see ''Sliding (Translation) Directions'') value of half the door width in the direction of the door handle. This will gently move the door out as it rotates to clear any solid on that side as in this diagram:<br>
[[Image:DoorClip.jpg]]<br>
Half a door width will typically be about 2. Any 'attachments' such as door handles will still synchronize with the door movement whether the door is rotating, sliding, or both.

Brush Door Centre of Rotation:<br>
The centre of rotation of a brush door ''can'' be changed. The default origin point of a brush is at its centre. Therefore a default rotating brush door will rotate around its centre when you first create it. So, mappers will commonly need to move that rotation point to a corner or even to some other offset position for example, for an openable window using the door function.

Put simply, to move the rotation point of a brush door you need to move the entity origin relative to the brush(es.)

Moving the entity origin (centre of rotation) relative to a brush door:

* Select the brush door
* Select ''Vertices mode'' (default shortcut key is {{key|name=V}} or button on top toolbar 'Select Vertices')
* Drag the door's entity origin to the point where you want the door to rotate. This should be on the corner on the leading edge side (the side to where the door is opening.) to avoid clipping as in this diagram....
[[Image:getCorner.jpg]]
* You should now find that door rotates around that point.

===Rotate Direction and Open Angle===

By default, rotating doors open anti-clockwise (viewed from above) by 90 degrees from the start orientation. If you want to change this edit the ''rotate'' property in the entity inspector. Don't confuse this ''rotate'' property with the ''rotation'' property. In the entity inspector remember that to see the inherited rotate property you must check the box 'Show inherited properties'.

The three values shown in the rotate property are degrees from the closed position around Y Z X (absolute map axes Front, Top, Side views in DR's ortho view.)

* Positive Y = Open clockwise (Dark Radiant grid front view, looking north)
* Negative Y = Open anti-clockwise (Dark Radiant grid front view, looking north)

* Positive Z = Open anti-clockwise (Dark Radiant grid top view, looking down)
* Negative Z = Open clockwise (Dark Radiant grid top view, looking down)

* Positive X = Open anti-clockwise (Dark Radiant grid side view, looking west)
* Negative X = Open clockwise (Dark Radiant grid side view, looking west)

There is a problem when you come to rotations that are not around the main Y Z X axes of the map, for instance a drawbridge that lowers down to the south east. You might think you can combine Y Z X values to get the result you want - and this can be done (for south east use 45 45 90) but it is a bit of a kludge and the drawbridge twists eccentrically as it lowers (though it arrives correctly!)

The values are in the range -179 to +180. Positive values give an anti-clockwise opening rotation (looking down from above) and negative values give a clockwise opening rotation. The value 180 is unique in that it continues in an anti-clockwise rotation when closing rather than returning clockwise so might be used if you can think of some object that might need such a motion when frobbed!

Edit the rotate value by selecting it and using the input box at the bottom and clicking the check(tick) button. That will change the angle the door will open to. Note that the line with the original default of 0 90 0 will still be there but your new entry will be added on a separate line and that is the one that will work in the game. CAUTION: when adjusting later make sure you have your new line selected and not the original! If you do it will appear to change but your first setting will remain unaltered.

Examples:
* 0 90 0 = Opens anti-clockwise round the entity's 'vertical' to 90 degrees - typical default vertical door.
* 0 0 90 = Lowers a drawbridge from the entity 'vertical' to horizontal.
* 0 0 -45 = Opens clockwise by 45 degrees viewed from the east side. This might suit a skylight in a sloping roof.

'rotate' cannot be combined with translate motions (see [[#Sliding (Translation) Amount and Direction]]) in one door; you need to bind one door to another and link they by targetting one to the other. By that means you can produce exotic and useful motions. A door opening against an upward-sloping floor can thus have a ''lifting hinge'' and raise up slightly to clear the floor; a door can rotate towards you and slide back to one side very effectively.

===Sliding (Translation) Amount and Direction===

By default a Dark Mod door will rotate open. For most sliding doors you want to stop them rotating as well as make them slide. You cannot delete (remove) the ''rotate'' property - you have to set the ''rotate'' property to 0 0 0 to stop a door rotating (see ''Rotate Direction and Open Angle''.)

Now edit the ''translate'' property value by selecting it (remember to have inherited properties box checked) and using the input box at the bottom and clicking the check(tick) button. That will change the distance the door will slide to. Note that the line with the original default of 0 0 0 will still be there but your new entry will be added on a separate line and that is the one that will work in the game. CAUTION: when adjusting later make sure you have your new line selected and not the original! If you do it will appear to change but your first setting will remain unaltered.

Typically (but not always) you will want your sliding door to slide the width of the door. The three values in the translate property by default are 0 0 0 and are X Y Z ''absolute map'' values (irrespective of door orientation) where:

* Positive X = Slide East (Right side of Dark Radiant grid in top view)
* Negative X = Slide West (Left side of Dark Radiant grid in top view)
* Positive Y = Slide North (top of Dark Radiant grid in top view)
* Negative Y = Slide South (bottom of Dark Radiant grid in top view)
* Positive Z = Slide Up (Top of Dark Radiant grid in side views)
* Negative Z = Slide Down (Bottom of Dark Radiant grid in side views)

So for a 50 unit wide door you want to slide fully to the east you would use 50 0 0 for the translate property values. A 100 unit portcullis sliding vertically up would need 0 0 100 to be fully raised.

=== Doors Collision/Push Behaviour ===
Doors push all entities by default, except for the player. Doors will also stop moving when anything blocks their movement. However, this default behaviour can be changed by setting appropriate spawnargs:

Set '''push_player''' to '''1''' to let the player be pushed by this door:
"push_player" "1" // Push the player too (default is off)

By default '''stop_when_blocked''' is set to 1 and if a door is blocked by an entity then even if the entity is removed afterwards, the door stays where it is. The next frob will close the door.

Set '''stop_when_blocked''' to '''0''' to prevent the door from ending the opening sequence when anything blocks its way. It will still pause - but continue to open if the block is removed.
"stop_when_blocked" "0" // door keeps moving after being blocked (default is off)
With this setting, doors will still stop at blocking entities (the player, for instance), but will continue to move when the entity moves out of the way.

There is another spawnarg which stops a door pushing a moveable. Apply this to the ''moveable'', not the door...

"notPushable" "1"

===Door Sounds===

There are multiple ways to put sounds on doors.

''snd_open'' <br>
Sound is triggered as the door begins to open.

''snd_opened'' <br>
Sound is triggered when the door finishes opening. Defaults to "nosound".

''snd_move''<br>
The sound plays while the door moves. Defaults to "nosound".

''snd_close'' <br>
Sound is triggered as the door finishes closing.

The following sounds should be left on the default sound in most cases so players clearly know what is going on:

''snd_locked''<br>
The sound played when a player or an AI tries to open a locked door.

''snd_unlock string''<br>
The sound played when a door is unlocked.

You can silence any of these sounds by setting the following properties as shown:

''snd_open nosound''<br>
''snd_close nosound''

Don't just use a dash - as it seems to cause a sound of its own.

===Sound Propagation through Doors and Doorways===

''This information will change significantly with the release of 2.0. See'' [[Controlling Sound Loss Across Portals]]

The sound volume reduction to the player (ie, the sound the player hears) is fixed and constant in a cvar which adds a distance factor to the original sound. It is recommended that you do not change that because it will affect other FMs. Currently there is no way to change the way that sound to the player is reduced through doors and doorways.

Sound propagation to AI, eg, impact sounds or guard yells is treated separately:

Sound propagation to AI relies on visportals. For details study [[Sound Propagation: Part 1]] and [[Sound Propagation: Part 2]] as well as [[Visportals]] This tutorial will just cover the relevant sound and sound propagation ''properties'' of doors. If you set the ''show inherited properties'' box in the entity inspector you can see them as described here.

Remember, the following have no effect on what the player hears through a door or doorway.

''loss_open''<br>
Drop in sound volume in dB propagated to AI (not player) when going through an open door. (default 1dB)

''loss_closed''<br>
Drop in sound volume in dB propagated to AI (not player) when going through a closed door. (default 15dB) You would want to set this very high to block all sound with a thick door but very low for a barred gate for example.

''loss_double_open''<br>
Drop in sound volume in dB propagated to AI (not player) when going through double doors when only one is open. (default 1dB)

There are also various sound properties for lockpicking:<br>
''snd_lockpick_pin_1 through 14'' and ''snd_lockpick_pin_success''

===Allowing the Player to Interrupt Door Motion===

The door property ''interruptable'' determines whether a door can be stopped by frobbing while it is opening or closing. It is enabled (i.e., set to 1) by default. Then the player, by frobbing to start the normal opening, then frobbing again to interrupt, can open a door to any position, e.g., slightly ajar to peek through. Another frob will begin closing, and so on with any additional frobs to stop/reverse-direction.

Be aware that an rotating-style door, when left ajar, will subsequently open or close more slowly than normal in an angular-velocity sense. It instead takes the same time as a full (uninterrupted) opening or closing would take in seconds, as given by ''move_time'' discussed next.

===Speed of Door Opening and Closing===

Rotating Door Speed:<br>
The time a rotating door takes to open or close is set in the ''move_time'' property, no matter what its maximum open angle may be. So with rotation set at, say, 150 degrees the door just opens faster than at, say, 80 degrees. To change this value, make sure the door is selected then...

* Right click the entity inspector and check ''show inherited properties''
* Scroll down, select ''move_time''
* Edit the second line of the input box ''below'' the properties window to the time you want.
* The time is in seconds and decimal fractions can be used. The default is currently 1.75 seconds.

Sliding Door Speed:<br>
The speed of a sliding door is set in the ''translate_speed'' property. To add this, make sure the door is selected then...

* Right click the entity inspector and check ''show inherited properties''
* Scroll down, select ''translate_speed''
* Edit the second line of the input box ''below'' the properties window to the speed you want.
* The speed is in Dark Radiant grid units per second.
* The default is 0 and if set to this then the door slides open in one second whatever the distance, great or small.
* CAUTION: It is assumed ''translate'' has been changed from its default value of 0 0 0. If not, a non-zero ''translate_speed'' may cause problems.

===Visportals and Doors===

A visportal face surrounded by solid at its edges and in contact with a door is closed when the door is closed and enabled when the door is open. In most cases you will place a visportal in contact with a working door unless you can see through the door (such as a true glass door or barred gate*.) For full details see [[Visportals]].

''*As of 2.0 it is possible to make visportals that remain transparent when closed for gates and windows. See'' [[Controlling Sound Loss Across Portals]]

==Auto-Closing/Opening Doors==
Doors that automatically close after being open for some time are easy to setup: Each frobmover entity supports these spawnargs:

;"auto_close_time":Set this to something >= 0 to let the mover automatically close (again) after this time when being fully opened (measured in seconds). Defaults to -1, which means 'do not autoclose'. The event is also activated when the mover starts at the open position at map start.
;"auto_open_time":"Set this to something >= 0 to let the mover automatically open (again) after this time when being fully closed (measured in seconds). Defaults to -1, which means 'do not autoopen'. The event is also activated when the mover starts at the closed position at map start.

<div class="toccolours mw-collapsible mw-collapsed">
Before auto_close_time and the AI Door Management spawnargs next were provided, a more laborious method was used to auto-close doors as if AI were closing doors behind them. Hit "Expand" to review it.
<div class="mw-collapsible-content">I have one door that I particularly want the AI to close as there is a bit of frame lag inside if not. So I set this up and it works good as an auto-closing door - not as good as a true AI closing door as it will auto close when the player goes through as well but it does look very effective to see AI going through and closing the door behind them. Not tested exhaustively so I don't know if there could be any downside. Here's what to do....

First a quick summary to make it more clear:

'''''A trigger_relay is used both as a relay AND carries a stim. We put the trigger_relay with its stim in the path of the open door. The door has a response property. When it opens and contacts the stim its response is to send a signal back to the relay. The relay pauses then closes the door...'''''

* First, optionally give your door a suitable name like autodoor1, whatever.
* Copy that name to the clipboard.

Next we need a relay with a delay:

* Create entity > darkmod > trigger_relay

* Place it roughly at the position the door will be at when open and to be on the safe side 3/4th of the way to the far end of the door (not the hinge end) to give max distance from the close door.

* Add the property 'target' and paste in the door name you just copied.

* Give the relay itself a name, eg, autoDoor_relay_1, and copy that name to the clipboard, you'll need that too in a bit.

* Add the property delay and the value 3 - this is the delay in seconds before the door will close; 3 seems about right but 2 might be worth a try because to that 3 is added a random value between 0 to 0.5 seconds from the Time Interval we entered for the stim firings.

* Add the property 'wait' and the value 3. This is the time before it can work again in seconds. If you set it too low then in theory the door might trigger again but in this situation I don't think it's possible. Too long, eg, one minute, and it won't work if the AI goes back through the door before then. If this value is -1 then the whole thing will only work ONCE so might be used for an AI who goes through once, closes it behind him, but you don't want it to be an autodoor thereafter.

That's the relay, now we add a stim to it:

* Still with the trigger relay selected, go to {{menu|Entity|Stim/Response}}

* Custom stim tab.

* Click Add stim type, select the new custom stim type you just made at the bottom of the list and type in eg, autoDoorStim at top right in the input box.

* Click the stim tab and the little drop down arrow against the 'type' selector at bottom left and you should see your new custom stim name. Select it.

* Select the new autoDoorStim in the list and on the right you need only type in the radius box 15.0 There is quite a lot of room for error. I had it working on 10 and also on 25. The value should be less than the distance to the closed door else it will trigger open! But no so small that the door might not reach it.

* Select the check box for Time Interval and enter 500 (millisecs.) This is so it doesn't keep firing more frequently than is necessary. This stim will be firing all through your mission whether the door is used or not so if you had dozens of these then maybe it would affect performance. Too big a number and there may be a long delay before the door shuts - but it will be random depending on the next time the stim happens to fire. We'll control the delay we want more precisely later.

* Click {{ok}} to confirm it.

That's the stim set up, now for the response to it which is put on the door....

* Select the doorm, then use {{menu|Entity|Stim/response}} and select the response tab.

* Click the little drop down arrow against the 'type' selector at bottom left and you should see your new custom stim name. Select it.

* Right click in the big ''Response Effects'' box on the bottom right of the panel.

* Add New Effect and you should get a default 'Activate Response' response added to the list. Double click it.

* In the Effect selector at the stop select 'Trigger'

* in the Target box, paste in the name of the relay you copied or you can select it from the list at the little arrow.

* Leave the Activator box empty.

* Click {{apply}} and then {{ok}} on the main S & R panel bottom right.

It should now work. No need to wait for an AI, just frob the door and watch it close itself. If not, check the position of the stim brush is close to where the door stops when open.</div>
</div>

==AI Door management==

By default AI will open doors and close them behind them. Here are some spawnargs '''on the door''' the mapper can use to modify that behaviour:

;"ai_should_not_handle" :If set to 1, AI will not attempt to handle it and add it to the forbidden areas (so that it doesn't try to path through). They might still walk through the door when it is open though. Useful if you have some special use door that you don't want the AI to operate.

;"ai_should_not_close" :If set to 1, AI will not close the door behind them unless it obstructs them.

;"canRemainOpen" :If set to 1, it's the same as "ai_should_not_close, with the added behavior that this is ignored if the door needs to be relocked, or the door is marked "shouldBeClosed". '''(This spawnarg is available starting in TDM 2.02.)'''

Spawnargs '''on the AI''' that the mapper can use:

;"canCloseDoors" :Added in 2.12. Defaults to 1. If set to 0, the AI will not close doors after passing through them.

To get AI to unlock/relock specific doors there are two methods:

1. Provide the AI with the key, as detailed in the def_attach method in [[#Keys_carried_by_AI]] above.

2. Add the following spawnarg/value to the AI:

;"can_unlock" ''<doorname>''

For additional doors on the same AI use ''can_unlock1 doorname', `can_unlock2 doorname' etc. '''Do NOT use can_unlock_1.'''

If both (1) and (2) are used, then the AI can still go through the door after the player pickpockets the key. Otherwise, unless someone else opens the door for the AI, a typical sequence is that the AI checks their pockets for the missing key, stalls a bit at the locked door, and then (with now-better pathing algorithms) the AI uses an alternate route to the next path_corner, or "mentally" skips ahead in the route to next reachable node and goes there.

===Door Handling Positions===

It is also possible to set custom door handling positions for the AI. This is especially useful when the standard routine that lets the AI choose their standing positions while opening and closing the door fails, leaving them standing still, or circling around in front of the door helplessly.

Place a movers > ''atdm:door_handling_position'' entity where you want the AI to stand while opening/closing the door from this side.

On the door, you need to set the spawnarg "door_handle_position" "name_of_door_handling_position". You can also place a ''door_handling_position'' on each side of the door, and the AI will automatically choose the right one. In this case, you need to set spawnargs with "door_handle_position_1" etc., and the corresponding names of the ''door_handling_position'' entities on the door.

The ''door_handling_position'' entities can also carry spawnargs that define the behaviour of the AI, which are useful for example for doors that can only be opened or locked from one side:

'''"ai_no_open"''' If set to "1", the AI will not try to open the door from this side (but will still walk through when the door is already open).

'''"ai_no_close"''' If set to "1", the AI will not attempt to close the door from this side.

'''"ai_no_unlock"''' If set "1", the AI will not be able to unlock the door from this side, but still use it when it is not locked.

'''"ai_no_lock"''' If this is set "1", the AI will not lock the door from this side.

===Door Controllers===

'''Available in TDM 2.02+'''

You can design a door so it's operated by buttons or levers or switches (aka ''controllers'').

A controller is simply an entity that targets the door. Typical examples of entities that can be used are:

* Buttons: atdm:mover_button
* Levers: atdm:switch_rotate_lever
* Switch: atdm:mover_lever
* Lock: atdm:froblock. (See also next section)

1. Set up the door in the normal manner. It can be a rotating door, a sliding door, a locked door, etc.

2. Turn off the "frobable" spawnarg on the door. ("frobable" "0")

3. Create a controller entity on each side of the door. If you're setting up a locked door using atdm:froblock, there's no need to put any locking information on the controllers. When the game starts, it will transfer any locking information from the door to the controllers.

4. Give each controller the door as a target.

Both the player and any AI that wants to use the door will use the controllers to operate it. Any key, "can_unlock", or lockpick settings you would normally use at the door are now used at the controllers.

Controllers and ''door_handling_position'' entities can be used on the same door, but in that situation the ''door_handling_position'' entities don't define where the AI stands to operate the door. They simply provide the "ai_no_*" spawnargs that define AI behavior on each side of the door.

If you wish, you could provide a controller on only one side of the door instead of both sides. Note that, since the door is not frobable, the player won't be able to operate the door from the non-controller side.

====More about Using a Separate "Froblock" Lock Plate====
''by Geep, 2021-22''

Froblock, just discussed as a controller method, actually predated the controller concept in TDM. Here we recap that earlier context, with an alternative treatment of highlighting, and thoughts on texturing and usage.

Suppose you want to have a lock plate (typically mounted on a door frame or wall) that opens a nearby door, where the door and lock plate highlight separately. A traditional way is to adapt the ''froblock'' method described under the "Making your own" section of [[Containers, Chests, etc.]]

Basically, your door is the "chest lid" (of class atdm:mover_door) and your lock is the "chest body" (of class atdm:froblock). Set the properties as described in the wiki. There is a stock texture (darkmod/door/keyhole_metal_001) you can use to decorate a surface of your lock plate, or a patch on it. This method is probably most apt for small hatches and grates designed for the player alone, and with no handles, or non-turning handles attached with "bind".

===AI and 'non-frobable' Doors===
Be aware that the 'frobable' spawnarg only applies to the player, not AI. If you set a door to be non-frobable (i.e. 'frobable' '0'), AI can still operate it by interacting directly with it, even if it has a controller. For example they will do this if:

* they are fleeing or chasing the player
* the door has a controller but the AI can't reach it (for example the controller is on the other side of the door)

The best way to mitigate this is to use Door Handling Position entities (see above) with the 'ai_no_open' spawnarg set on them.

===AI locking doors behind them===

If one AI is involved (no one else is in the queue), he'll lock it behind him if he had to unlock it in the first place.

Prior to TDM 1.08, if more than one AI is using the door at the same time (there's a queue), the first AI unlocks the door, and the last AI through will only lock it if it's marked "should_always_be_locked" AND they have a "can_unlock" for that door or they have a key for that door. The last AI to use the door doesn't know that the first AI found it locked, because that info is kept per AI, and not per door.

Starting in TDM 1.08, if the first AI in a door queue found the door locked, that information is remembered by the door and the last AI through uses it to relock the door, as long as they have a "can_unlock" for that door or they have a key for that door.

In the rare case where a door is set up to use door-handling position entities (necessary for AI to use sliding doors), either or both of those entities can have the "ai_no_lock" spawnarg, which means AI aren't allowed to lock the door from that side.

==Initially Blocking a Door - Partially or Fully==
''by Geep 2021''

Suppose you have a door that you want to start out either as unopenable, or able to open just a crack, then later, after something happens, be fully openable and operational. One method known to work:

* Create a moveable object that the opening door runs into and tries to push.
* Arrange that the far side of the moveable object is jammed against some immovable worldspawn.

Here's two specific examples that use a wooden plank moveable:

* In "Perilous Refuge", a plank blocks the door leading out of the player's starting location, until the player carries it away.
* At the end of "Away0" (WIP 2021), the player tries to open a door. But if preconditions aren't met, the occupant seems to let the door open only a crack and complains. Blockage is done by an unseen plank resting on the floor hitting a knob of worldspawn. Preconditions met causes a "$plank.remove()" script call.

Other methods that you might think would work but don’t:

* Block with a func_static object, or an unjammed moveable with "notpushable 1" set. In both cases, the door travels through the object.
* In advance, "grab" an unjammed moveable to make it appear "solid" to the physics engine. (This was tested by having the player manipulate it; if it had worked, a “grabber” script call might suffice.)
* Dynamically change the door’s "rotate" limit from script using "setSpawnArg"; this function would only work before you spawn the door, not afterwards.

(Others possibilities not yet tested:

* Change "rotate" using the "setKey" script function; for some spawnargs this works even after spawn.
* Create a moveable and bind it to the world entity.
* If you are mainly interested in initially blocking an AI from using a door: it's possible that the AI re-reads the spawnargs for what doors it's allowed to open. Try adding a frob Response to the key (Entity -> Stim/Response... -> Response) with an effect that sets the “can_unlock" spawnarg on that AI to "-".)

==Controlling a Door by Scripting==
''by Geep 2021''
===If Unlocked===

Simply use, for example with a door named ''door1'':

$door1.Open();
...
$door1.Close();

Alternatively, toggle it open or closed with:

$door1.frob();

If the door has "interruptable 1" (which is the default with atdm:mover_door), you can also frob() it twice to leave it ajar. Interpose and adjust a sys.wait(...) to tune it.
===If Locked===

You need to unlock it first. Changing the door's "locked" spawnarg value won't work. Instead you will use:

$door1.Unlock();

But there are complications. By default, the door has spawnarg "open_on_unlock 1". So, assuming you didn't change that, you'd think unlocking the door would open it. But this spawnarg will be ignored if the gamer has global menu option "Open Doors on Unlock" set to Off. Assuming you want to reliably have the door open, do this:

$door1.Unlock(); // MAYBE will open door too.
sys.wait(3); // If so, wait for door to fully open. Value may need adjusting based on door's speed
$door1.Open(); // Otherwise, open it now.

The wait is added, because otherwise, the opening begun by Unlock may be stopped by Open with the door only partially open. (Probably an alternative to using sys.wait here is to zero the door's "interruptable" spawnarg.)

==Doors as Triggers==

''by Ishtvan & greebo''

Doors (or any binary frob mover, buttons, levers, etc) now have the option to [[Triggers|trigger]] their target on closing or opening. (For definition purposes, a button is defined as "closed" in the state when it starts out and "open" in the state you press it down to. I know that's a little non-intuitive, but it came from deriving from doors).

New spawnargs on frob movers:
;"trigger_on_open" :If set to 1, this binary mover will trigger its targets when it starts out completely closed and is opened.
;"trigger_when_opened":If set to 1, this binary mover will trigger its targets when it is completely opened. Code defaults to 0.
;"trigger_on_close":If set to 1, this binary mover will trigger its targets when it completely closes after being open.

== Suspicious Doors ==

If you give a door the spawnarg '''"shouldBeClosed" "1"''', then AI will treat it as suspicious if they find the door open.

Doors with that spawnarg should work like this:

- an AI opening the door knows he's not to become suspicious if he opened the door

- nearby AI alerted by the open door will also not react if they can see the door, and can see the AI that opened it

- AI who come upon the open door later probably won't be able to see the AI that opened it, so they'll treat it as suspicious

- if the AI who opened the door comes upon the door later, and it's still open, and no one's touched it since he opened it, he'll see his name on the door and won't become suspicious. "Oh, crap. I forgot to close it earlier."

- If an AI comes upon an open door that should be closed, he should close it whether he becomes suspicious or not.

'''Post TDM 2.00:'''
- AI turn to look at a door they see opening. The player can crack open a suspicious door to peek out w/o grabbing the attention of a nearby AI. After 5s, the AI will notice the cracked open door. Non-suspicious doors can be cracked open indefinitely w/o nearby AI noticing.

==Slanted or Tilted Doors==
Slanted or tilted doors can be made as follows:

1) Place your door, preferrably one of the prefab doors, which have a model door and model handle and all the rotation spawnargs pre-set.

2) rotate and place the door+handle model into place you want it to be. Now, if you use the door in the game, the door will rotate around the world z-axis, and not the door model z-axis (which is rotated).

3) to get the door to rotate around the door model z-axis, you must place a model (any model will do, and it can be placed anywhere in the map). Rotate the new model into the same orientation your door model was rotated, i.e. if you door is rotated 45 degrees around the x-axis, do the same rotation on the new model.

4) bind the doors on the new model. This makes the doors start rotating along the new model origin (which is rotated the same way as the doors).

5) working slanted door.

Do note, that all the rotated objects need to be models (suspicion, not tested). You can export DR built stuff into a model using the DR ase exporter script. For custom doors, remember that the exporter places the model origin at the map origin if you do not choose the "place origin in the middle of the object" option.

Also note that the AI probably cannot use slanted doors and might get stuck (suspicion, not tested).

There is a link to a test map here:
http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/?p=395486

==Skins: A Wide Variety of Door Textures==

This is to remind you that as with many Dark Mod models, there is a wide range of extras skins (textures) available for door models. There are now several basic door entities of different sizes so choose your size first. Then enter the spawnarg: skin with any temporary value. Now select it and click the skin button at the bottom of Dark Radiant's Entity Inspector and you will find a large of range of skin textures from which to select to give you a choice of appearances for your door.

==Extra Notes==

''func_darkmod_door'' is no longer used (just in case you come across it in the Dark Mod forums or wiki.) '''<code>atdm:mover_door</code>''' is the entity to use.

{{tutorial-editing}}

Doors

2025-11-06T20:05:08Z

Frost Salamander:

{{todo}}
''Written by Fidcal'' ''edit Baddcog''

==Quick Summary==

Quick way to get an unlocked door in your map:

* Insert one of the prefab doors complete with handles and select its skin property and click the button to change its skin appearance to whatever you want. Set any other properties you need.

Alternatively,

* Create a door from the entity list
* Use the "skin" spawnarg on the door to change its appearance.
* Create a handle from the entity list
* Add the ''door_handle'' property to the door and give it the name of the handle
* To the door handle add the value frob_peer and use the name of the door.
* To open clockwise, change the ''rotate'' property from <code>0 90 0</code> to <code>0 -90 0</code>

==Introduction==

This tutorial explains how to put doors into your map using Dark Radiant, as well as adjust them and their properties.

The rest of this tutorial assumes that you have a basic understanding of using DarkRadiant. If you haven't done so, please go read the [[Dark Radiant Must Know Basic Intro]] article first.

Additionally:

* Up, down, right, and left in Dark Radiant's ''top'' orthoview are regarded here as the standard map directions of North, South, East, and West where useful for clarity.
* Where the term ''brush'' is used with a door it mostly also applies to a door made up of a group of brushes and/or patches.
* Where the term ''door'' is used it often will also apply to any object you wish to rotate when frobbed, for instance an openable window, box lid, or even more exotic objects that the imaginative mapper might conceive like a signal, engine part, toy, or whatever. So long as it needs to turn or slide just a fixed amount when frobbed then return when frobbed again then the following applies.

==Door types==

All tangible objects in Dark Mod are ''entities'', having either a pre-made model shape or else brush/patch(es). So there are two ways to create a door in Dark Radiant: as a model door or a textured brush door (or a hybrid of the two).

Models are ready made door objects but cannot within Dark Radiant (at the time of writing) be resized, rescaled, cropped or clipped whereas brushes are very flexible in that respect and can be worked into custom shapes for your map, including secret doors that blend into walls and other surfaces.

Most of the current door models are found in two places along with the door handles.
*Model Viewer: doors created from here will be static in the world and have no props other than material type.
You can add any props to them to make them working doors. If nothing else it is a good place to view the different size and skin options for the doors.
*Entity List: most of the door models can be found here. These doors have properties already assigned so they are ready to be used. Only one base door of each type is listed, create the size/hinge count door you want (2 hinge doors have a 'no hinge' skin). You can choose a skin for the door once it has been created in the editor with the "skin" spawnarg (use the model name of the door you want, taken from the model list, as its value). This is the easiest way to create a door. The same goes for door handles.

Remember also that door functions may be applied to objects other than doors, such as openable windows, drawbridges, gates, etc. In fact, anything that needs a partial rotation or slide when frobbed then return when frobbed again, such as a signal device. Lockboxes and chests use similar properties.

You can create one door/handle set and copy/paste it, but you need to take great care that all the name props are changed to match in each clone. Otherwise you get handles that fly off when a distant door moves, and handles that don't move.

==Creating a Door==

Put simply, to make a door you will be creating an 'entity with model' or 'entity with brush' or some variation thereof.

===Creating a Model Door===

There are several approaches to making a model door; the simplest is to create a door from the entity list; or create a door from the model viewer (good for static unusable prop doors).

'''Entity List''':

*Deselect everything in editor by hitting the Esc button
*Right-click an ortho view and select Create Entity
*Navigate to darkmod/movers/''atdm:door_...'', choose the door you want
*Click Add
*To change its appearance, add a "skin" spawnarg to the door, with the value being the model name of the door you want.

You now have a workable door in your level.

'''Model Viewer''':

* Right click in the orthoview, select ''Create Model'' then <code>darkmod</code> and select a door.
* Note that you can left drag the image in the ''Choose Model'' dialog to rotate it around.
* Click [[Image:Button ok.png]] and you have a static door.
* If you want to make it work (openable, frobbable) then:
** Select the entity inspector,
** Select the top classname line so it highlights
** Select the func_static line in the input box ''below'' the properties window.
** Edit <code>func_static</code> to <code>atdm:mover_door</code>
** Click {{check}} or press {{key-enter}}

Alternatively you can do it the old way:

* Create any temporary brush
* Right click in orthoview and select <code>Create Entity</code> then <code>atdm:mover_door</code>.
* Left lick the model name line in the entity inspector.
* Below it on the ''Entity Inspector'' panel you should now see a button 'Choose Model'
* Left click it, select a door model from the darkmod group.
* Note that you can left drag the image in the ''Choose Model'' dialog to rotate it around.
* The temporary brush was deleted.

In all three instances, you now have a working door with default properties.

Name your door by adding the prop (or modifing it) to name ''My_Door_1''. You can use any name that you feel is appropriate but all doors with handles attached ''must'' have their own specific name. Use the name My_Door_1 for your first attempt as it will be referenced when you get around to attaching handles (see below).

To add a handle and other adjustments, see [[#Customising and Adjusting Door Properties]] below.

===Creating a Textured Brush Door===

'''Tip:''' If unsure of size then you might insert a temporary human AI first to get a sense of height.

==== The simplest brush door: ====

* Drag out a new brush to the size required, eg, a seven foot high door is 84" x 1.1 = about 90 units in Dark Radiant.
* Give it a door texture from the texture browser (or wall texture for a secret door)
* Right click in orthoview and select ''Create Entity'' then <code>atdm:mover_door</code>

You now have a working door but it will rotate around its center. To move the rotation point to where you want the door hinges to be:
* Select the door and press 'v' or the ''Select Vertices'' button to enter vertex editing mode. The door's origin will show up as a small green square in the middle of the brush.
* In top-down orthoview, move the origin from the center to the corner of the brush. This is easiest in drag mode ('q' or the ''Resize'' button), although you can use translate mode ('w' or the ''Translate'' button) by manually selecting the vertex first.

==== Multi-brush doors: ====

More complex multi-brush doors can be created using the [[Clipper]] tool, CSG, etc. - this is not covered in this tutorial. Then assign <code>atdm:mover_door</code> for that whole brush structure. Also you can collect various brushes positioned together in relation to one another as needed, select them all, then assign <code>atdm:mover_door</code> for the group. All the brushes will be children of the <code>atdm:mover_door</code> entity and will rotate and be frobbable, etc. as one unit, as one door. To add further brushes or even model shapes later see the section on [[#Adding handles and other items to doors]].

Name your door by adding the prop (or modifing it) to name My_Door_1. You can use any name that you feel is appropriate but all doors with handles attached must have their own specific name. Use the name My_Door_1 for your first attempt as it will be referenced when you get around to attaching handles (see below). (repeated from above in case you didn't choose to create a model door)

=== Double Doors ===
Double doors are automatically recognised by the code when the doors are spawned. The prerequisite is that both doors are sharing/touching the same visportal. The spawnarg ''auto_setup_double_door'' (which defaults to "1") will take care of setting up the open/lock peer relationship between the two doors. The doors will open/close and lock/unlock along with each other as a result.

What happens behind the scenes: the doors are adding each other to their internal open_peer and lock_peer list, which causes the double doors to perform the same action when frobbed or used.

Note that ''auto_setup_double_door'' will not set the frob_peer relationship, i.e. each door will frob-highlight on its own without highlighting the other door. You'll need to add that spawnarg manually if you want to highlight the entire double door as one.

==Customising and Adjusting Door Properties==

Handles, lockplates, etc. can be added to doors and door properties can be adjusted for rotation, sliding, locking, and more.

Some of the door models have hinge plates and lockboxes that are reskinnable with a good variety of skins.

===Door handles and other door attachments===

'''Summary: just add the property ''bind'' with the door's name to the attachment and position it where you want it on the door. If it's a ''atdm:mover_door_handle'' then it automatically will work as a handle but you can bind virtually anything.'''
You can add handles and other items to doors such that they move correctly with the door whether rotating, sliding, or both and even if the door is not vertical such as a skylight or trapdoor.
Handle models come in two types, ''single handles'' and ''double handles''. A single handle is one sided, this means the handle will be inside the door or outside the door, but not both. A double handle has a lever on the inside of the door and a handle on the outside of the door. Each has benefits.

*'''''Single door handles''''':
Single door handles can be used on a static door, a door that's just for show that no AI's or the player can use. In this case you should just create a door handle from the model viewer, it will be static and have no properties such as scripts. It is for looks only. Note that TDM is trying to establish the expectation that decorative doors that cannot be opened do not have handles (though not all maps follow this).

I will call this ''multiple handles'', see more below.

These can also be useful on brush doors created in the editor that may be very thin or very wide.

*'''''Double door handles''''':
These are models have have a handle inside and outside. The bonus is that they only use one entity. Maps are limited to about 4,000 entities but when you count lights, AI, sound speakers, ect... you can run out of entities quickly on a large map. If you plan on building a large map this is the way to go, even in a small map they have benefits, namely that you only have to attach one handle per door.

Whether you decide to use a single handle or a double handle you must first follow the instructions below and attach one handle first. If you choose a double handle, follow the instructions below and you are done. If you choose a single handle type follow the instructions then also follow the ''multiple handle'' instructions for the second handle.

Both single and double handle types can be found in two places. The model viewer which will create a static model good for show, you can manually add props to make them work OR you can look in the entity browser.
Using a handle from the entity browser saves you a little bit of time as some props are already added, you just need to add the frob_peer names for the doors/handles and the door_handle name to the door.

=== Adding a working model door handle===

Quick summary:
* Create a model or brush handle and make it an ''atdm:mover_door_handle'' entity.
* Position it on your door. Use the opposite side from the door's multicolor X-Y-Z indicator (highlight the door to see it) if it's not obvious which side it goes on.
* '''Bind''' the handle to the door (bind <doorname>)
* It should now be a working handle though may need adjustments of rotation etc. see later.

Important: read preceding section on door handle types and performance issues first.

This works with both a model door and a brush door:

'''Rotation''':
* By default the door handle entity rotates ''anti-clockwise'' (looked at from the front) then springs back. A ''double handle'' model is OK but two singles (see ''Multiple door handles'' below) need more care as only one is the functioning entity and the other is just attached to it. So anti-clockwise is fine for a door with its hinge on the left and the handle on the right - the handle will rotate down then spring back. If you put the functioning door handle on the other side you will have to change the default ''rotate'' property from -45 0 0 to 45 0 0. '''''Therefore it is easier to generally put this handle on the side of the door where the hinge is on the left and the non-functioning attachment handle on the other side.'''''
*If your door only needs one handle, eg, a cupboard door, and from outside its hinge is on the right then you will need to change the ''rotate'' property of the handle as described above.

'''''The functioning handle entity:'''''
* Create an entity door handle (movers folder) or create a brush or model handle and assign it the entity ''atdm:mover_door_handle''.
* Position it where you wish on your door.
* '''Bind''' the handle to the door, by adding the "bind" spawnarg to the handle.

You now have a working door handle with default properties.

*'''Multiple door handles''':
Now that you've got a handle attached to one side of the door it is time to add one to the other side (unless you used a double handle).
* Create the new handle. The single handles come in left and right persuasions. A door needs a left facing handle on one side and a right facing handle on the other, so if you have already added the left handle create a right handle and line it up on the other side of the door.
* Name this handle. I prefer to keep a naming convention for each door and it's respective handles, it makes things alot easier. The door is named '''My_Door_1''', the first handle is named '''My_Handle_1''' so name the second handle '''My_Handle_1_1'''. This will make it stay with the first handle in the entity list. This is important to keep organized. If you name it My_Handle_2 then when you get to another door named My_Door_2 you'll be confused.
* Place and '''bind''' that handle to your door.

You now have two single door handles on either side of the door that rotate together as if they were physically attached.

'''To add a brush to a brush door''':
* Select the new brush ''and'' the brush door all together; ''the entity '''must''' be selected '''last'''.''
* Use {{menu|Edit|Reparent primitives}}. This ensures the parent entity adopts the new item(s).
* If you have trouble selecting them in the orthoview because other brushes, etc. get selected then try in the camera view or as a last resort move them temporarily to an open area (but keep them in the same positions relative to each other.) Use {{key-shift}}+{{LMB}} on new item(s) then {{key-shift}}+{{LMB}} on main entity. Once they are all selected, use the {{menu|Edit|Reparent primitives}}.

'''To add ''model'' static items''': knockers, hinges, static handles etc. to a ''Model Door'':
* Select item
* Right click in orthoview and select ''Create Entity'' then <code>entity func_static</code>
* Position it where you wish on your door.
* To synchronize this with your particular door you need to add the property ''bind'' and the individual door name to the brush entity. To do this...
** Select the model door.
** In the entity inspector, select the ''name'' line
** Select the bottom line in the input box ''below'' the properties window.
** Copy the name
** Deselect the door with {{key-esc}}
** Select the brush entity
** Add a property "bind" to it.
** Change the value of the property by pasting in the door name
** Click {{check}} or press {{key-enter}}

'''To add ''brush'' static items''': knockers, hinges, static handles to a Model Door:
* This method is not ideal but it seems to work OK.
* Select the brush.
* Right click in orthoview and select Create Entity then ''atdm:mover_door_handle''
* Position it where you wish on your door.

To synchronize this with your particular door you need to add the property ''door_handle'' on the door, and give as the value the name of the brush you just created.

This brush turns like a handle. To stop it:

* Adding ''rotate 0 0 0'' or disabling the handle script won't help.
* Add a real working handle (as in the section above ''To add a working model door handle...'' and it must be added LAST.)

If you don't want too see a real working handle added maybe try another tiny brush with the handle function and hide it inside the door?

===Locking Doors===

To lock a door check the ''show inherited properties'' in the entity inspector for a ''atdm:mover_door'' entity and you should see the ''locked'' property. Select it and in the input box below the properties you can change its value:

* 0 = unlocked (default)
* 1 = locked

If locked it will require an entity that is associated with it to be able to act as a key to unlock it.

Currently door handles on locked doors will rotate when frobbed, they will bounce back though and the door will stay locked until unlocked.

===Keys===

Assigning specific keys to specific doors is simple.

* It is recommended that you create an existing key entity. These keys have all required props, they just need to be named.

Alternatively you can create a key from the Model Viewer and want it to be useable
* Make sure it has the properties:
useable 1 [so it can be used by the door]
frobable 1
inv_name <unique name>
inv_category Keys
inv_target player1
inv_icon guis/assets/hud/inventory_icons/<icon name>
inv_stackable 0 or 1 where 1 can be used on all copies of the same key so they show as one entry in the inventory with a total.

Add to the door the property <code>used_by</code> with the name of the key as the value. Multiple keys can open the same door by using several <tt>used_by</tt> spawnargs:

"used_by" "doorkey_1"
"used_by1" "doorkey_2

==== Keys Carried by AI ====

So you have a door and you have a guard AI and you want the guard to be able to open/close/lock the door, but you also want the player to be able to pickpocket the key. Keys can be attached to AI in two ways.

''The Def_Attach Method''. This method is the best one for doors that you expect the AI to operate. It uses spawnargs to spawn the key at game start.

*"def_attach6" "atdm:prop_silverkey" // the entity to spawn - in this case a key.
*"pos_attach6" "belt_back_right" // where the key will spawn on the Ai.
*"name_attach6" "door_key" // this gives 'attach6' arg the name "door_key" and is the name the arg "used_by" will need, eg: "used_by" "door_key"
*"set inv_name on door_key" "Door key" // The name the key get when the play adds it to their inventory.
*"set name on door_key" "door_key" // here it gets a name to be used in the map in general.

For more info on this method, see [[Attaching Props to AI]].

''The Bind Method''. This lacks the animation finesse of def_attach, but does let you see the key in DR. The method is particularly helpful in, say, adding a second key to an AI in the back middle of a belt. The AI cannot use a bound key to open a locked door; the workaround is to fake it with "can_unlock" as discussed further below. Or to use bound keys mainly for items the AI will not attempt to open, such as hatches, duct covers, or chests.

* Load a key entity
* Position where you want it in relation to the AI, and bind it to them (i.e., "bind" "<AIname>")
* Add the spawnarg "bindToJoint" "Hips" (or another location like LeftHips_Dummy; see AI for list)
* Adjust existing spawnargs accordingly (that is, be sure the name and door's/chest's "used_by" match, if you aren't using a prefab chest with key). This is for the benefit of the player after pickpocketing the key; as stated above, the AI itself can't use it for unlocking.

For more info on this method, see [[Attaching_Items]] and [[BindToJoint]].

====Keys Carried by Player====

With a door's key selected in your inventory and the door highlighted, you can...
* unlock it (which will also auto-open if enabled) by either frobbing it or hitting the Use key (typically U or Enter).
* lock (or relock) it via the Use key. Why do this? To avoid pursuit, or to lure guards into a room, and then lock them in (if they don't have a key or specific can_unlock powers).

====Master Key for Testing====

By default, ALL locks can be opened by any key named ''key_master''. Just create a key in your map, name it ''key_master'' and it becomes a master key for use while testing. Add inv_map_start 1 to it so it is in the player inventory at game start. Remember to delete it when your mission is finished.

====Automatically Removing Keys from Player Inventory After Use====
If a fan mission has a lot of keys it can clog up the player inventory. If the key is single-use, it can be useful to automatically remove it from the player inventory after use. Below is a way to do it using a simple setup and a generic script function that can be used for multiple doors.

=====Generic Version=====

You'll need the following entities, preferably set up near each other in your map:
* The door entity itself
* A trigger_count entity
* An atdm:target_callscriptfunction entity
* some random entity for the target_callscriptfunction to target (explanation below)

The below diagram shows the spawnargs and targeting required for the setup:
[[File:Key remove2.png|left|thumb]]

<div style="clear: both"></div>
The script being called ('openDoor') is defined in fms/<mapname>/maps/<mapname>.script and looks like this:

void openDoor(entity target, entity door, entity callscriptfunction)
{
string keyName = door.getKey("used_by");
entity key = sys.getEntity(keyName);
$player1.replaceInvItem(key, $null_entity);
}

Explanation as follows:

'''For the door:'''
* '''trigger_on_open''' spawnarg: The door is configured to trigger its targets when it opens
* target '''trigger_count''' entity: this is the entity that is triggered when the door is opened
* '''used_by''' spawnarg: This names the key entity required for unlocking the door
* The other spawnargs are just the usual for setting the door as locked and unpickable

'''trigger_count entity:'''
* When triggered, this entity will in turn trigger the script that removes the key from the player inventory.
* '''count''' spawnarg: This is set to 1 because we only want the key removal script called once - the first time the player opens the door.
* this entity targets the atdm:target_callscriptfunction, which contains details of the script to execute

'''atdm:target_callscriptfunction entity:'''
* '''call''' spawnarg: This is the name of the script function to call
* '''foreach''' spawnarg: This version of the script event provides access to the 'activator', or the entity that triggered it (in this case, the door). Using that information we can obtain the key name. See [[A to Z Scripting: Ways of calling a script#target_callscriptfunction|here]] for details.
* '''target any static entity''': For this version of the script event to work, the target_callscriptfunction entity needs to target something. This can be any static entity in the map (i.e. one that won't get removed or anything). I usually just target the nearest entity (e.g. a light or a lamp, or a model). This provides no functionality in the context of this tutorial, it just satisfies the conditions of the script event.

'''The script:'''
* Pretty self-explanatory. The script gets the name of the key entity via the '''used_by''' spawnarg on the door, retrieves the key entity, and then replaces it in the player inventory with a null entity, effectively removing it.
* Any door can use this script as its generic (although they will need their own trigger_count and target_callscriptfunction entities)

=====Simpler, No-script Version=====
This is similar to above, but is more limited. You need to hard-code the key name as a spawnarg on an atdm:target_itemremove entity as they key name can't be automatically determined. This makes it slightly more error-prone as we're naming entities in more than one place, but ideal if you're uncomfortable with scripting.

[[File:Key remove4.png|left|thumb]]
<div style="clear: both"></div>

Explanation as follows:

'''atdm:target_itemremove entity:'''
* '''unique_item ''' spawnarg: The name of the key to remove from the player inventory

===Lockpicks===
''by Baddcog''

There are two lock pick types.
*'''s'''=snake
*'''t'''=triangular

A lock can be set with many pins. Each pin has a click sequence and each needs a designated lockpick type (see above). Keep in mind that the lockpicking in The Darkmod is much more involved than in T2 or T3. The player has to listen to sounds or watch a handle or lockbar to know when a lock is pin is picked.

This means that authors can be very evil and really frustrate the player, in which case their missions will probably not be played. So be nice to the player and don't waste your time. Use simple locks for the most part and save complicated locks for important sections and to build tension. Don't make the player have 20 pins to pick all with different lockpicks. In most cases 1 or 2 pins will suffice and it isn't necessary to use both lockpicks on every lock.
Also try to include a lock lever on lockboxes or chests, door handles will rotate as the pins are being picked. This gives the player visual clues to help with the picking (and essential in noisy environments where you can't hear the clicks.)
IMO this system is a huge leap foward for lockpicking but also has the ability to completely frustrate the player as stated above. Keep this in mind when designing your lockpick systems.

These props go on the door itself, or the lid of a chest, eg,
*'''lock_pins''' 1327
*'''lock_picktype''' stts

The lock_pins property specifies how many pins each lockpicktype has.
The lockpick_type property specifies how many times the player has to switch picks and which pick they have to use. You can see there must always be an equal number of lock_pins and lock_picktypes specified

So looking at the example above we have lockpick_type s(snake), t(triangular), t(triangular), and s(snake). The player will have to use these lockpicks in this order. Once the snake lockpick's pins are open the player can advance to the triangular pick and so forth.
5 is added to every click sequence so 5 is the minimum click pattern even if you set it to 0.
In the example above the lockpins specify in order which pick types have how many pins, so the s pick has 1 + 5 = 6 clicks, the t pick has 8 and so on.
The above is a difficult lock and to avoid annoying the player it is best only used rarely on a special lock like an important big vault door. Ordinary footlockers and common doors can be just 1 or 2 click sequences, eg, lock_pins 2 and lock_picktype t means the player uses one pick and listens for the end of one sequence of 7 clicks.

lockpick_rotate - is placed on the door. It is the amount the visible rotating handle or pin rotates while picking. For a rotating handle or lockbar normally ignore this and leave the default. During lockpicking it oscillates and progresses to the normal full turn of the handle. Example 0 45 0.

lockpick_translate - is placed on the door. It is the amount the visible handle or pin moves in a straight line while picking. Use this if you have eg, a lockbar that you want to move in a straight line and not rotate, eg sliding catch. Example 0 -5 0

By default, doors are pickable. If you don't set up the above lockpick spawnargs then it can't be picked. So there is normally no need to enable lockpicking - just set up the above spawnargs. There is a ''pickable'' spawnarg set to 1 by default. If set to 0 then the door becomes unpickable. But hard to think of an application except in testing or perhaps a special custom situation where it is switched by script perhaps.

===Open, Partially Open, or Closed Door at Game Start===

By default, doors are closed at game start. If you want a door to be already open or partially open then do the following.

'''Note well: Create all doors in their ''closed'' position. Adjust as follows and they will automatically be at the open position when game starts.'''

Already Open Rotating Door:
* Select the door.
* Select the entity inspector
* Check ''show inherited properties''
* Select the ''open'' property
* Edit the value to 1 in the input box below and tick the check button
* The door will now be fully open at game start.

* If you want it only partly open:
* Make sure its ''open'' property is set to 1 as above.
* Right click the entity inspector and select ''add property''
* Click the + sign on the left of the top line where atdm:mover_door is listed to open the folder. (if atdm:mover_door is not listed then the entity was likely changed from eg, func_static. If so, save the map and reload to update the add property list)
* scroll down, select ''start_rotate'' then click {{ok}}
* This adds it to the property list.
* Now select ''start_rotate'' in the property list.
* Edit the bottom line of the input box ''below'' the properties window to the angle you want in the same form as described in the ''Rotate Direction and Open Angle'' section. So for example, to have a door that has a fully open default ''rotate'' value of 0 90 0 to start only half open you would give it a ''start_rotate'' value of 0 45 0.
* In a similar way add the property ''first_frob_open".
* Set it to 1 and a partly open door should then open fully on the first frob.
* Set it to 0 and a partly open door should close on the first frob.

Already Open Sliding Door:
* Select the door.
* Select the entity inspector
* Check ''show inherited properties''
* Select the ''open'' property
* Edit the value to 1 in the input box below and click {{check}} or press {{key-enter}}
* The door will now be fully open at game start.

* If you want it only partly open:
* Right click the entity inspector and select ''add property''
* Make sure its ''open'' property is set to 1
* Click the + sign on the left of the top line where atdm:mover_door is listed to open the folder.
* scroll down, select ''start_position'' then click OK. (if atdm:mover_door is not listed then the entity was likely changed from eg, func_static. If so, save the map and reload to update the add property list)
* This adds it to the property list.
* Now select ''start_position'' in the property list.
* Edit the bottom line of the input box ''below'' the properties window to the position you want in the same form as described in the ''Sliding (Translation) Amount and Direction'' section. So for example, to have a door that has a fully open default ''translate'' value of 0 50 0 to start only half open you would give it a ''start_position'' value of 0 25 0.
* In a similar way add the property ''first_frob_open".
* Set it to 1 and a partly open door should then open fully on the first frob.
* Set it to 0 and a partly open door should close on the first frob.

===Rotation Centre, Pivot, Hinge point===

The centre of rotation of a door is at the origin point of its entity and the door rotates with reference to the orientation of that origin point, not the world map. See ''Rotate Direction...'' for more about that. This section only deals with the ''position'' of the rotation centre in the door.

Model Door Centre of Rotation:<br>
The centre of rotation of a model door cannot be changed within Dark Radiant. Because a model door rotates around the centre 'spine' of its back edge this will cause clipping (penetration into solid) as in this example (where the door is set to open to 89 degrees for clarity):<BR>[[Image:modelClipping.jpg]]<BR> So care is needed with placement. You will not normally position a door right next to a wall as in the example but against a shallow frame so clipping will barely be noticeable but either way it can be fixed. You can correct it by adding a translation (see ''Sliding (Translation) Directions'') value of half the door width in the direction of the door handle. This will gently move the door out as it rotates to clear any solid on that side as in this diagram:<br>
[[Image:DoorClip.jpg]]<br>
Half a door width will typically be about 2. Any 'attachments' such as door handles will still synchronize with the door movement whether the door is rotating, sliding, or both.

Brush Door Centre of Rotation:<br>
The centre of rotation of a brush door ''can'' be changed. The default origin point of a brush is at its centre. Therefore a default rotating brush door will rotate around its centre when you first create it. So, mappers will commonly need to move that rotation point to a corner or even to some other offset position for example, for an openable window using the door function.

Put simply, to move the rotation point of a brush door you need to move the entity origin relative to the brush(es.)

Moving the entity origin (centre of rotation) relative to a brush door:

* Select the brush door
* Select ''Vertices mode'' (default shortcut key is {{key|name=V}} or button on top toolbar 'Select Vertices')
* Drag the door's entity origin to the point where you want the door to rotate. This should be on the corner on the leading edge side (the side to where the door is opening.) to avoid clipping as in this diagram....
[[Image:getCorner.jpg]]
* You should now find that door rotates around that point.

===Rotate Direction and Open Angle===

By default, rotating doors open anti-clockwise (viewed from above) by 90 degrees from the start orientation. If you want to change this edit the ''rotate'' property in the entity inspector. Don't confuse this ''rotate'' property with the ''rotation'' property. In the entity inspector remember that to see the inherited rotate property you must check the box 'Show inherited properties'.

The three values shown in the rotate property are degrees from the closed position around Y Z X (absolute map axes Front, Top, Side views in DR's ortho view.)

* Positive Y = Open clockwise (Dark Radiant grid front view, looking north)
* Negative Y = Open anti-clockwise (Dark Radiant grid front view, looking north)

* Positive Z = Open anti-clockwise (Dark Radiant grid top view, looking down)
* Negative Z = Open clockwise (Dark Radiant grid top view, looking down)

* Positive X = Open anti-clockwise (Dark Radiant grid side view, looking west)
* Negative X = Open clockwise (Dark Radiant grid side view, looking west)

There is a problem when you come to rotations that are not around the main Y Z X axes of the map, for instance a drawbridge that lowers down to the south east. You might think you can combine Y Z X values to get the result you want - and this can be done (for south east use 45 45 90) but it is a bit of a kludge and the drawbridge twists eccentrically as it lowers (though it arrives correctly!)

The values are in the range -179 to +180. Positive values give an anti-clockwise opening rotation (looking down from above) and negative values give a clockwise opening rotation. The value 180 is unique in that it continues in an anti-clockwise rotation when closing rather than returning clockwise so might be used if you can think of some object that might need such a motion when frobbed!

Edit the rotate value by selecting it and using the input box at the bottom and clicking the check(tick) button. That will change the angle the door will open to. Note that the line with the original default of 0 90 0 will still be there but your new entry will be added on a separate line and that is the one that will work in the game. CAUTION: when adjusting later make sure you have your new line selected and not the original! If you do it will appear to change but your first setting will remain unaltered.

Examples:
* 0 90 0 = Opens anti-clockwise round the entity's 'vertical' to 90 degrees - typical default vertical door.
* 0 0 90 = Lowers a drawbridge from the entity 'vertical' to horizontal.
* 0 0 -45 = Opens clockwise by 45 degrees viewed from the east side. This might suit a skylight in a sloping roof.

'rotate' cannot be combined with translate motions (see [[#Sliding (Translation) Amount and Direction]]) in one door; you need to bind one door to another and link they by targetting one to the other. By that means you can produce exotic and useful motions. A door opening against an upward-sloping floor can thus have a ''lifting hinge'' and raise up slightly to clear the floor; a door can rotate towards you and slide back to one side very effectively.

===Sliding (Translation) Amount and Direction===

By default a Dark Mod door will rotate open. For most sliding doors you want to stop them rotating as well as make them slide. You cannot delete (remove) the ''rotate'' property - you have to set the ''rotate'' property to 0 0 0 to stop a door rotating (see ''Rotate Direction and Open Angle''.)

Now edit the ''translate'' property value by selecting it (remember to have inherited properties box checked) and using the input box at the bottom and clicking the check(tick) button. That will change the distance the door will slide to. Note that the line with the original default of 0 0 0 will still be there but your new entry will be added on a separate line and that is the one that will work in the game. CAUTION: when adjusting later make sure you have your new line selected and not the original! If you do it will appear to change but your first setting will remain unaltered.

Typically (but not always) you will want your sliding door to slide the width of the door. The three values in the translate property by default are 0 0 0 and are X Y Z ''absolute map'' values (irrespective of door orientation) where:

* Positive X = Slide East (Right side of Dark Radiant grid in top view)
* Negative X = Slide West (Left side of Dark Radiant grid in top view)
* Positive Y = Slide North (top of Dark Radiant grid in top view)
* Negative Y = Slide South (bottom of Dark Radiant grid in top view)
* Positive Z = Slide Up (Top of Dark Radiant grid in side views)
* Negative Z = Slide Down (Bottom of Dark Radiant grid in side views)

So for a 50 unit wide door you want to slide fully to the east you would use 50 0 0 for the translate property values. A 100 unit portcullis sliding vertically up would need 0 0 100 to be fully raised.

=== Doors Collision/Push Behaviour ===
Doors push all entities by default, except for the player. Doors will also stop moving when anything blocks their movement. However, this default behaviour can be changed by setting appropriate spawnargs:

Set '''push_player''' to '''1''' to let the player be pushed by this door:
"push_player" "1" // Push the player too (default is off)

By default '''stop_when_blocked''' is set to 1 and if a door is blocked by an entity then even if the entity is removed afterwards, the door stays where it is. The next frob will close the door.

Set '''stop_when_blocked''' to '''0''' to prevent the door from ending the opening sequence when anything blocks its way. It will still pause - but continue to open if the block is removed.
"stop_when_blocked" "0" // door keeps moving after being blocked (default is off)
With this setting, doors will still stop at blocking entities (the player, for instance), but will continue to move when the entity moves out of the way.

There is another spawnarg which stops a door pushing a moveable. Apply this to the ''moveable'', not the door...

"notPushable" "1"

===Door Sounds===

There are multiple ways to put sounds on doors.

''snd_open'' <br>
Sound is triggered as the door begins to open.

''snd_opened'' <br>
Sound is triggered when the door finishes opening. Defaults to "nosound".

''snd_move''<br>
The sound plays while the door moves. Defaults to "nosound".

''snd_close'' <br>
Sound is triggered as the door finishes closing.

The following sounds should be left on the default sound in most cases so players clearly know what is going on:

''snd_locked''<br>
The sound played when a player or an AI tries to open a locked door.

''snd_unlock string''<br>
The sound played when a door is unlocked.

You can silence any of these sounds by setting the following properties as shown:

''snd_open nosound''<br>
''snd_close nosound''

Don't just use a dash - as it seems to cause a sound of its own.

===Sound Propagation through Doors and Doorways===

''This information will change significantly with the release of 2.0. See'' [[Controlling Sound Loss Across Portals]]

The sound volume reduction to the player (ie, the sound the player hears) is fixed and constant in a cvar which adds a distance factor to the original sound. It is recommended that you do not change that because it will affect other FMs. Currently there is no way to change the way that sound to the player is reduced through doors and doorways.

Sound propagation to AI, eg, impact sounds or guard yells is treated separately:

Sound propagation to AI relies on visportals. For details study [[Sound Propagation: Part 1]] and [[Sound Propagation: Part 2]] as well as [[Visportals]] This tutorial will just cover the relevant sound and sound propagation ''properties'' of doors. If you set the ''show inherited properties'' box in the entity inspector you can see them as described here.

Remember, the following have no effect on what the player hears through a door or doorway.

''loss_open''<br>
Drop in sound volume in dB propagated to AI (not player) when going through an open door. (default 1dB)

''loss_closed''<br>
Drop in sound volume in dB propagated to AI (not player) when going through a closed door. (default 15dB) You would want to set this very high to block all sound with a thick door but very low for a barred gate for example.

''loss_double_open''<br>
Drop in sound volume in dB propagated to AI (not player) when going through double doors when only one is open. (default 1dB)

There are also various sound properties for lockpicking:<br>
''snd_lockpick_pin_1 through 14'' and ''snd_lockpick_pin_success''

===Allowing the Player to Interrupt Door Motion===

The door property ''interruptable'' determines whether a door can be stopped by frobbing while it is opening or closing. It is enabled (i.e., set to 1) by default. Then the player, by frobbing to start the normal opening, then frobbing again to interrupt, can open a door to any position, e.g., slightly ajar to peek through. Another frob will begin closing, and so on with any additional frobs to stop/reverse-direction.

Be aware that an rotating-style door, when left ajar, will subsequently open or close more slowly than normal in an angular-velocity sense. It instead takes the same time as a full (uninterrupted) opening or closing would take in seconds, as given by ''move_time'' discussed next.

===Speed of Door Opening and Closing===

Rotating Door Speed:<br>
The time a rotating door takes to open or close is set in the ''move_time'' property, no matter what its maximum open angle may be. So with rotation set at, say, 150 degrees the door just opens faster than at, say, 80 degrees. To change this value, make sure the door is selected then...

* Right click the entity inspector and check ''show inherited properties''
* Scroll down, select ''move_time''
* Edit the second line of the input box ''below'' the properties window to the time you want.
* The time is in seconds and decimal fractions can be used. The default is currently 1.75 seconds.

Sliding Door Speed:<br>
The speed of a sliding door is set in the ''translate_speed'' property. To add this, make sure the door is selected then...

* Right click the entity inspector and check ''show inherited properties''
* Scroll down, select ''translate_speed''
* Edit the second line of the input box ''below'' the properties window to the speed you want.
* The speed is in Dark Radiant grid units per second.
* The default is 0 and if set to this then the door slides open in one second whatever the distance, great or small.
* CAUTION: It is assumed ''translate'' has been changed from its default value of 0 0 0. If not, a non-zero ''translate_speed'' may cause problems.

===Visportals and Doors===

A visportal face surrounded by solid at its edges and in contact with a door is closed when the door is closed and enabled when the door is open. In most cases you will place a visportal in contact with a working door unless you can see through the door (such as a true glass door or barred gate*.) For full details see [[Visportals]].

''*As of 2.0 it is possible to make visportals that remain transparent when closed for gates and windows. See'' [[Controlling Sound Loss Across Portals]]

==Auto-Closing/Opening Doors==
Doors that automatically close after being open for some time are easy to setup: Each frobmover entity supports these spawnargs:

;"auto_close_time":Set this to something >= 0 to let the mover automatically close (again) after this time when being fully opened (measured in seconds). Defaults to -1, which means 'do not autoclose'. The event is also activated when the mover starts at the open position at map start.
;"auto_open_time":"Set this to something >= 0 to let the mover automatically open (again) after this time when being fully closed (measured in seconds). Defaults to -1, which means 'do not autoopen'. The event is also activated when the mover starts at the closed position at map start.

<div class="toccolours mw-collapsible mw-collapsed">
Before auto_close_time and the AI Door Management spawnargs next were provided, a more laborious method was used to auto-close doors as if AI were closing doors behind them. Hit "Expand" to review it.
<div class="mw-collapsible-content">I have one door that I particularly want the AI to close as there is a bit of frame lag inside if not. So I set this up and it works good as an auto-closing door - not as good as a true AI closing door as it will auto close when the player goes through as well but it does look very effective to see AI going through and closing the door behind them. Not tested exhaustively so I don't know if there could be any downside. Here's what to do....

First a quick summary to make it more clear:

'''''A trigger_relay is used both as a relay AND carries a stim. We put the trigger_relay with its stim in the path of the open door. The door has a response property. When it opens and contacts the stim its response is to send a signal back to the relay. The relay pauses then closes the door...'''''

* First, optionally give your door a suitable name like autodoor1, whatever.
* Copy that name to the clipboard.

Next we need a relay with a delay:

* Create entity > darkmod > trigger_relay

* Place it roughly at the position the door will be at when open and to be on the safe side 3/4th of the way to the far end of the door (not the hinge end) to give max distance from the close door.

* Add the property 'target' and paste in the door name you just copied.

* Give the relay itself a name, eg, autoDoor_relay_1, and copy that name to the clipboard, you'll need that too in a bit.

* Add the property delay and the value 3 - this is the delay in seconds before the door will close; 3 seems about right but 2 might be worth a try because to that 3 is added a random value between 0 to 0.5 seconds from the Time Interval we entered for the stim firings.

* Add the property 'wait' and the value 3. This is the time before it can work again in seconds. If you set it too low then in theory the door might trigger again but in this situation I don't think it's possible. Too long, eg, one minute, and it won't work if the AI goes back through the door before then. If this value is -1 then the whole thing will only work ONCE so might be used for an AI who goes through once, closes it behind him, but you don't want it to be an autodoor thereafter.

That's the relay, now we add a stim to it:

* Still with the trigger relay selected, go to {{menu|Entity|Stim/Response}}

* Custom stim tab.

* Click Add stim type, select the new custom stim type you just made at the bottom of the list and type in eg, autoDoorStim at top right in the input box.

* Click the stim tab and the little drop down arrow against the 'type' selector at bottom left and you should see your new custom stim name. Select it.

* Select the new autoDoorStim in the list and on the right you need only type in the radius box 15.0 There is quite a lot of room for error. I had it working on 10 and also on 25. The value should be less than the distance to the closed door else it will trigger open! But no so small that the door might not reach it.

* Select the check box for Time Interval and enter 500 (millisecs.) This is so it doesn't keep firing more frequently than is necessary. This stim will be firing all through your mission whether the door is used or not so if you had dozens of these then maybe it would affect performance. Too big a number and there may be a long delay before the door shuts - but it will be random depending on the next time the stim happens to fire. We'll control the delay we want more precisely later.

* Click {{ok}} to confirm it.

That's the stim set up, now for the response to it which is put on the door....

* Select the doorm, then use {{menu|Entity|Stim/response}} and select the response tab.

* Click the little drop down arrow against the 'type' selector at bottom left and you should see your new custom stim name. Select it.

* Right click in the big ''Response Effects'' box on the bottom right of the panel.

* Add New Effect and you should get a default 'Activate Response' response added to the list. Double click it.

* In the Effect selector at the stop select 'Trigger'

* in the Target box, paste in the name of the relay you copied or you can select it from the list at the little arrow.

* Leave the Activator box empty.

* Click {{apply}} and then {{ok}} on the main S & R panel bottom right.

It should now work. No need to wait for an AI, just frob the door and watch it close itself. If not, check the position of the stim brush is close to where the door stops when open.</div>
</div>

==AI Door management==

By default AI will open doors and close them behind them. Here are some spawnargs '''on the door''' the mapper can use to modify that behaviour:

;"ai_should_not_handle" :If set to 1, AI will not attempt to handle it and add it to the forbidden areas (so that it doesn't try to path through). They might still walk through the door when it is open though. Useful if you have some special use door that you don't want the AI to operate.

;"ai_should_not_close" :If set to 1, AI will not close the door behind them unless it obstructs them.

;"canRemainOpen" :If set to 1, it's the same as "ai_should_not_close, with the added behavior that this is ignored if the door needs to be relocked, or the door is marked "shouldBeClosed". '''(This spawnarg is available starting in TDM 2.02.)'''

Spawnargs '''on the AI''' that the mapper can use:

;"canCloseDoors" :Added in 2.12. Defaults to 1. If set to 0, the AI will not close doors after passing through them.

To get AI to unlock/relock specific doors there are two methods:

1. Provide the AI with the key, as detailed in the def_attach method in [[#Keys_carried_by_AI]] above.

2. Add the following spawnarg/value to the AI:

;"can_unlock" ''<doorname>''

For additional doors on the same AI use ''can_unlock1 doorname', `can_unlock2 doorname' etc. '''Do NOT use can_unlock_1.'''

If both (1) and (2) are used, then the AI can still go through the door after the player pickpockets the key. Otherwise, unless someone else opens the door for the AI, a typical sequence is that the AI checks their pockets for the missing key, stalls a bit at the locked door, and then (with now-better pathing algorithms) the AI uses an alternate route to the next path_corner, or "mentally" skips ahead in the route to next reachable node and goes there.

===Door Handling Positions===

It is also possible to set custom door handling positions for the AI. This is especially useful when the standard routine that lets the AI choose their standing positions while opening and closing the door fails, leaving them standing still, or circling around in front of the door helplessly.

Place a movers > ''atdm:door_handling_position'' entity where you want the AI to stand while opening/closing the door from this side.

On the door, you need to set the spawnarg "door_handle_position" "name_of_door_handling_position". You can also place a ''door_handling_position'' on each side of the door, and the AI will automatically choose the right one. In this case, you need to set spawnargs with "door_handle_position_1" etc., and the corresponding names of the ''door_handling_position'' entities on the door.

The ''door_handling_position'' entities can also carry spawnargs that define the behaviour of the AI, which are useful for example for doors that can only be opened or locked from one side:

'''"ai_no_open"''' If set to "1", the AI will not try to open the door from this side (but will still walk through when the door is already open).

'''"ai_no_close"''' If set to "1", the AI will not attempt to close the door from this side.

'''"ai_no_unlock"''' If set "1", the AI will not be able to unlock the door from this side, but still use it when it is not locked.

'''"ai_no_lock"''' If this is set "1", the AI will not lock the door from this side.

===Door Controllers===

'''Available in TDM 2.02+'''

You can design a door so it's operated by buttons or levers or switches (aka ''controllers'').

A controller is simply an entity that targets the door. Typical examples of entities that can be used are:

* Buttons: atdm:mover_button
* Levers: atdm:switch_rotate_lever
* Switch: atdm:mover_lever
* Lock: atdm:froblock. (See also next section)

1. Set up the door in the normal manner. It can be a rotating door, a sliding door, a locked door, etc.

2. Turn off the "frobable" spawnarg on the door. ("frobable" "0")

3. Create a controller entity on each side of the door. If you're setting up a locked door using atdm:froblock, there's no need to put any locking information on the controllers. When the game starts, it will transfer any locking information from the door to the controllers.

4. Give each controller the door as a target.

Both the player and any AI that wants to use the door will use the controllers to operate it. Any key, "can_unlock", or lockpick settings you would normally use at the door are now used at the controllers.

Controllers and ''door_handling_position'' entities can be used on the same door, but in that situation the ''door_handling_position'' entities don't define where the AI stands to operate the door. They simply provide the "ai_no_*" spawnargs that define AI behavior on each side of the door.

If you wish, you could provide a controller on only one side of the door instead of both sides. Note that, since the door is not frobable, the player won't be able to operate the door from the non-controller side.

====More about Using a Separate "Froblock" Lock Plate====
''by Geep, 2021-22''

Froblock, just discussed as a controller method, actually predated the controller concept in TDM. Here we recap that earlier context, with an alternative treatment of highlighting, and thoughts on texturing and usage.

Suppose you want to have a lock plate (typically mounted on a door frame or wall) that opens a nearby door, where the door and lock plate highlight separately. A traditional way is to adapt the ''froblock'' method described under the "Making your own" section of [[Containers, Chests, etc.]]

Basically, your door is the "chest lid" (of class atdm:mover_door) and your lock is the "chest body" (of class atdm:froblock). Set the properties as described in the wiki. There is a stock texture (darkmod/door/keyhole_metal_001) you can use to decorate a surface of your lock plate, or a patch on it. This method is probably most apt for small hatches and grates designed for the player alone, and with no handles, or non-turning handles attached with "bind".

===AI and 'non-frobable' Doors===
Be aware that the 'frobable' spawnarg only applies to the player, not AI. If you set a door to be non-frobable (i.e. 'frobable' '0'), AI can still operate it by interacting directly with it, even if it has a controller. For example they will do this if:

* they are fleeing or chasing the player
* the door has a controller but the AI can't reach it (for example the controller is on the other side of the door)

The best way to mitigate this is to use Door Handling Position entities (see above) with the 'ai_no_open' spawnarg set on them.

===AI locking doors behind them===

If one AI is involved (no one else is in the queue), he'll lock it behind him if he had to unlock it in the first place.

Prior to TDM 1.08, if more than one AI is using the door at the same time (there's a queue), the first AI unlocks the door, and the last AI through will only lock it if it's marked "should_always_be_locked" AND they have a "can_unlock" for that door or they have a key for that door. The last AI to use the door doesn't know that the first AI found it locked, because that info is kept per AI, and not per door.

Starting in TDM 1.08, if the first AI in a door queue found the door locked, that information is remembered by the door and the last AI through uses it to relock the door, as long as they have a "can_unlock" for that door or they have a key for that door.

In the rare case where a door is set up to use door-handling position entities (necessary for AI to use sliding doors), either or both of those entities can have the "ai_no_lock" spawnarg, which means AI aren't allowed to lock the door from that side.

==Initially Blocking a Door - Partially or Fully==
''by Geep 2021''

Suppose you have a door that you want to start out either as unopenable, or able to open just a crack, then later, after something happens, be fully openable and operational. One method known to work:

* Create a moveable object that the opening door runs into and tries to push.
* Arrange that the far side of the moveable object is jammed against some immovable worldspawn.

Here's two specific examples that use a wooden plank moveable:

* In "Perilous Refuge", a plank blocks the door leading out of the player's starting location, until the player carries it away.
* At the end of "Away0" (WIP 2021), the player tries to open a door. But if preconditions aren't met, the occupant seems to let the door open only a crack and complains. Blockage is done by an unseen plank resting on the floor hitting a knob of worldspawn. Preconditions met causes a "$plank.remove()" script call.

Other methods that you might think would work but don’t:

* Block with a func_static object, or an unjammed moveable with "notpushable 1" set. In both cases, the door travels through the object.
* In advance, "grab" an unjammed moveable to make it appear "solid" to the physics engine. (This was tested by having the player manipulate it; if it had worked, a “grabber” script call might suffice.)
* Dynamically change the door’s "rotate" limit from script using "setSpawnArg"; this function would only work before you spawn the door, not afterwards.

(Others possibilities not yet tested:

* Change "rotate" using the "setKey" script function; for some spawnargs this works even after spawn.
* Create a moveable and bind it to the world entity.
* If you are mainly interested in initially blocking an AI from using a door: it's possible that the AI re-reads the spawnargs for what doors it's allowed to open. Try adding a frob Response to the key (Entity -> Stim/Response... -> Response) with an effect that sets the “can_unlock" spawnarg on that AI to "-".)

==Controlling a Door by Scripting==
''by Geep 2021''
===If Unlocked===

Simply use, for example with a door named ''door1'':

$door1.Open();
...
$door1.Close();

Alternatively, toggle it open or closed with:

$door1.frob();

If the door has "interruptable 1" (which is the default with atdm:mover_door), you can also frob() it twice to leave it ajar. Interpose and adjust a sys.wait(...) to tune it.
===If Locked===

You need to unlock it first. Changing the door's "locked" spawnarg value won't work. Instead you will use:

$door1.Unlock();

But there are complications. By default, the door has spawnarg "open_on_unlock 1". So, assuming you didn't change that, you'd think unlocking the door would open it. But this spawnarg will be ignored if the gamer has global menu option "Open Doors on Unlock" set to Off. Assuming you want to reliably have the door open, do this:

$door1.Unlock(); // MAYBE will open door too.
sys.wait(3); // If so, wait for door to fully open. Value may need adjusting based on door's speed
$door1.Open(); // Otherwise, open it now.

The wait is added, because otherwise, the opening begun by Unlock may be stopped by Open with the door only partially open. (Probably an alternative to using sys.wait here is to zero the door's "interruptable" spawnarg.)

==Doors as Triggers==

''by Ishtvan & greebo''

Doors (or any binary frob mover, buttons, levers, etc) now have the option to [[Triggers|trigger]] their target on closing or opening. (For definition purposes, a button is defined as "closed" in the state when it starts out and "open" in the state you press it down to. I know that's a little non-intuitive, but it came from deriving from doors).

New spawnargs on frob movers:
;"trigger_on_open" :If set to 1, this binary mover will trigger its targets when it starts out completely closed and is opened.
;"trigger_when_opened":If set to 1, this binary mover will trigger its targets when it is completely opened. Code defaults to 0.
;"trigger_on_close":If set to 1, this binary mover will trigger its targets when it completely closes after being open.

== Suspicious Doors ==

If you give a door the spawnarg '''"shouldBeClosed" "1"''', then AI will treat it as suspicious if they find the door open.

Doors with that spawnarg should work like this:

- an AI opening the door knows he's not to become suspicious if he opened the door

- nearby AI alerted by the open door will also not react if they can see the door, and can see the AI that opened it

- AI who come upon the open door later probably won't be able to see the AI that opened it, so they'll treat it as suspicious

- if the AI who opened the door comes upon the door later, and it's still open, and no one's touched it since he opened it, he'll see his name on the door and won't become suspicious. "Oh, crap. I forgot to close it earlier."

- If an AI comes upon an open door that should be closed, he should close it whether he becomes suspicious or not.

'''Post TDM 2.00:'''
- AI turn to look at a door they see opening. The player can crack open a suspicious door to peek out w/o grabbing the attention of a nearby AI. After 5s, the AI will notice the cracked open door. Non-suspicious doors can be cracked open indefinitely w/o nearby AI noticing.

==Slanted or Tilted Doors==
Slanted or tilted doors can be made as follows:

1) Place your door, preferrably one of the prefab doors, which have a model door and model handle and all the rotation spawnargs pre-set.

2) rotate and place the door+handle model into place you want it to be. Now, if you use the door in the game, the door will rotate around the world z-axis, and not the door model z-axis (which is rotated).

3) to get the door to rotate around the door model z-axis, you must place a model (any model will do, and it can be placed anywhere in the map). Rotate the new model into the same orientation your door model was rotated, i.e. if you door is rotated 45 degrees around the x-axis, do the same rotation on the new model.

4) bind the doors on the new model. This makes the doors start rotating along the new model origin (which is rotated the same way as the doors).

5) working slanted door.

Do note, that all the rotated objects need to be models (suspicion, not tested). You can export DR built stuff into a model using the DR ase exporter script. For custom doors, remember that the exporter places the model origin at the map origin if you do not choose the "place origin in the middle of the object" option.

Also note that the AI probably cannot use slanted doors and might get stuck (suspicion, not tested).

There is a link to a test map here:
http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/?p=395486

==Skins: A Wide Variety of Door Textures==

This is to remind you that as with many Dark Mod models, there is a wide range of extras skins (textures) available for door models. There are now several basic door entities of different sizes so choose your size first. Then enter the spawnarg: skin with any temporary value. Now select it and click the skin button at the bottom of Dark Radiant's Entity Inspector and you will find a large of range of skin textures from which to select to give you a choice of appearances for your door.

==Extra Notes==

''func_darkmod_door'' is no longer used (just in case you come across it in the Dark Mod forums or wiki.) '''<code>atdm:mover_door</code>''' is the entity to use.

{{tutorial-editing}}

File:Key remove4.png

2025-11-06T20:04:31Z

Frost Salamander:

diagram

Doors

2025-11-06T20:03:01Z

Frost Salamander: /* Automatically Removing Keys from Player Inventory After Use */

{{todo}}
''Written by Fidcal'' ''edit Baddcog''

==Quick Summary==

Quick way to get an unlocked door in your map:

* Insert one of the prefab doors complete with handles and select its skin property and click the button to change its skin appearance to whatever you want. Set any other properties you need.

Alternatively,

* Create a door from the entity list
* Use the "skin" spawnarg on the door to change its appearance.
* Create a handle from the entity list
* Add the ''door_handle'' property to the door and give it the name of the handle
* To the door handle add the value frob_peer and use the name of the door.
* To open clockwise, change the ''rotate'' property from <code>0 90 0</code> to <code>0 -90 0</code>

==Introduction==

This tutorial explains how to put doors into your map using Dark Radiant, as well as adjust them and their properties.

The rest of this tutorial assumes that you have a basic understanding of using DarkRadiant. If you haven't done so, please go read the [[Dark Radiant Must Know Basic Intro]] article first.

Additionally:

* Up, down, right, and left in Dark Radiant's ''top'' orthoview are regarded here as the standard map directions of North, South, East, and West where useful for clarity.
* Where the term ''brush'' is used with a door it mostly also applies to a door made up of a group of brushes and/or patches.
* Where the term ''door'' is used it often will also apply to any object you wish to rotate when frobbed, for instance an openable window, box lid, or even more exotic objects that the imaginative mapper might conceive like a signal, engine part, toy, or whatever. So long as it needs to turn or slide just a fixed amount when frobbed then return when frobbed again then the following applies.

==Door types==

All tangible objects in Dark Mod are ''entities'', having either a pre-made model shape or else brush/patch(es). So there are two ways to create a door in Dark Radiant: as a model door or a textured brush door (or a hybrid of the two).

Models are ready made door objects but cannot within Dark Radiant (at the time of writing) be resized, rescaled, cropped or clipped whereas brushes are very flexible in that respect and can be worked into custom shapes for your map, including secret doors that blend into walls and other surfaces.

Most of the current door models are found in two places along with the door handles.
*Model Viewer: doors created from here will be static in the world and have no props other than material type.
You can add any props to them to make them working doors. If nothing else it is a good place to view the different size and skin options for the doors.
*Entity List: most of the door models can be found here. These doors have properties already assigned so they are ready to be used. Only one base door of each type is listed, create the size/hinge count door you want (2 hinge doors have a 'no hinge' skin). You can choose a skin for the door once it has been created in the editor with the "skin" spawnarg (use the model name of the door you want, taken from the model list, as its value). This is the easiest way to create a door. The same goes for door handles.

Remember also that door functions may be applied to objects other than doors, such as openable windows, drawbridges, gates, etc. In fact, anything that needs a partial rotation or slide when frobbed then return when frobbed again, such as a signal device. Lockboxes and chests use similar properties.

You can create one door/handle set and copy/paste it, but you need to take great care that all the name props are changed to match in each clone. Otherwise you get handles that fly off when a distant door moves, and handles that don't move.

==Creating a Door==

Put simply, to make a door you will be creating an 'entity with model' or 'entity with brush' or some variation thereof.

===Creating a Model Door===

There are several approaches to making a model door; the simplest is to create a door from the entity list; or create a door from the model viewer (good for static unusable prop doors).

'''Entity List''':

*Deselect everything in editor by hitting the Esc button
*Right-click an ortho view and select Create Entity
*Navigate to darkmod/movers/''atdm:door_...'', choose the door you want
*Click Add
*To change its appearance, add a "skin" spawnarg to the door, with the value being the model name of the door you want.

You now have a workable door in your level.

'''Model Viewer''':

* Right click in the orthoview, select ''Create Model'' then <code>darkmod</code> and select a door.
* Note that you can left drag the image in the ''Choose Model'' dialog to rotate it around.
* Click [[Image:Button ok.png]] and you have a static door.
* If you want to make it work (openable, frobbable) then:
** Select the entity inspector,
** Select the top classname line so it highlights
** Select the func_static line in the input box ''below'' the properties window.
** Edit <code>func_static</code> to <code>atdm:mover_door</code>
** Click {{check}} or press {{key-enter}}

Alternatively you can do it the old way:

* Create any temporary brush
* Right click in orthoview and select <code>Create Entity</code> then <code>atdm:mover_door</code>.
* Left lick the model name line in the entity inspector.
* Below it on the ''Entity Inspector'' panel you should now see a button 'Choose Model'
* Left click it, select a door model from the darkmod group.
* Note that you can left drag the image in the ''Choose Model'' dialog to rotate it around.
* The temporary brush was deleted.

In all three instances, you now have a working door with default properties.

Name your door by adding the prop (or modifing it) to name ''My_Door_1''. You can use any name that you feel is appropriate but all doors with handles attached ''must'' have their own specific name. Use the name My_Door_1 for your first attempt as it will be referenced when you get around to attaching handles (see below).

To add a handle and other adjustments, see [[#Customising and Adjusting Door Properties]] below.

===Creating a Textured Brush Door===

'''Tip:''' If unsure of size then you might insert a temporary human AI first to get a sense of height.

==== The simplest brush door: ====

* Drag out a new brush to the size required, eg, a seven foot high door is 84" x 1.1 = about 90 units in Dark Radiant.
* Give it a door texture from the texture browser (or wall texture for a secret door)
* Right click in orthoview and select ''Create Entity'' then <code>atdm:mover_door</code>

You now have a working door but it will rotate around its center. To move the rotation point to where you want the door hinges to be:
* Select the door and press 'v' or the ''Select Vertices'' button to enter vertex editing mode. The door's origin will show up as a small green square in the middle of the brush.
* In top-down orthoview, move the origin from the center to the corner of the brush. This is easiest in drag mode ('q' or the ''Resize'' button), although you can use translate mode ('w' or the ''Translate'' button) by manually selecting the vertex first.

==== Multi-brush doors: ====

More complex multi-brush doors can be created using the [[Clipper]] tool, CSG, etc. - this is not covered in this tutorial. Then assign <code>atdm:mover_door</code> for that whole brush structure. Also you can collect various brushes positioned together in relation to one another as needed, select them all, then assign <code>atdm:mover_door</code> for the group. All the brushes will be children of the <code>atdm:mover_door</code> entity and will rotate and be frobbable, etc. as one unit, as one door. To add further brushes or even model shapes later see the section on [[#Adding handles and other items to doors]].

Name your door by adding the prop (or modifing it) to name My_Door_1. You can use any name that you feel is appropriate but all doors with handles attached must have their own specific name. Use the name My_Door_1 for your first attempt as it will be referenced when you get around to attaching handles (see below). (repeated from above in case you didn't choose to create a model door)

=== Double Doors ===
Double doors are automatically recognised by the code when the doors are spawned. The prerequisite is that both doors are sharing/touching the same visportal. The spawnarg ''auto_setup_double_door'' (which defaults to "1") will take care of setting up the open/lock peer relationship between the two doors. The doors will open/close and lock/unlock along with each other as a result.

What happens behind the scenes: the doors are adding each other to their internal open_peer and lock_peer list, which causes the double doors to perform the same action when frobbed or used.

Note that ''auto_setup_double_door'' will not set the frob_peer relationship, i.e. each door will frob-highlight on its own without highlighting the other door. You'll need to add that spawnarg manually if you want to highlight the entire double door as one.

==Customising and Adjusting Door Properties==

Handles, lockplates, etc. can be added to doors and door properties can be adjusted for rotation, sliding, locking, and more.

Some of the door models have hinge plates and lockboxes that are reskinnable with a good variety of skins.

===Door handles and other door attachments===

'''Summary: just add the property ''bind'' with the door's name to the attachment and position it where you want it on the door. If it's a ''atdm:mover_door_handle'' then it automatically will work as a handle but you can bind virtually anything.'''
You can add handles and other items to doors such that they move correctly with the door whether rotating, sliding, or both and even if the door is not vertical such as a skylight or trapdoor.
Handle models come in two types, ''single handles'' and ''double handles''. A single handle is one sided, this means the handle will be inside the door or outside the door, but not both. A double handle has a lever on the inside of the door and a handle on the outside of the door. Each has benefits.

*'''''Single door handles''''':
Single door handles can be used on a static door, a door that's just for show that no AI's or the player can use. In this case you should just create a door handle from the model viewer, it will be static and have no properties such as scripts. It is for looks only. Note that TDM is trying to establish the expectation that decorative doors that cannot be opened do not have handles (though not all maps follow this).

I will call this ''multiple handles'', see more below.

These can also be useful on brush doors created in the editor that may be very thin or very wide.

*'''''Double door handles''''':
These are models have have a handle inside and outside. The bonus is that they only use one entity. Maps are limited to about 4,000 entities but when you count lights, AI, sound speakers, ect... you can run out of entities quickly on a large map. If you plan on building a large map this is the way to go, even in a small map they have benefits, namely that you only have to attach one handle per door.

Whether you decide to use a single handle or a double handle you must first follow the instructions below and attach one handle first. If you choose a double handle, follow the instructions below and you are done. If you choose a single handle type follow the instructions then also follow the ''multiple handle'' instructions for the second handle.

Both single and double handle types can be found in two places. The model viewer which will create a static model good for show, you can manually add props to make them work OR you can look in the entity browser.
Using a handle from the entity browser saves you a little bit of time as some props are already added, you just need to add the frob_peer names for the doors/handles and the door_handle name to the door.

=== Adding a working model door handle===

Quick summary:
* Create a model or brush handle and make it an ''atdm:mover_door_handle'' entity.
* Position it on your door. Use the opposite side from the door's multicolor X-Y-Z indicator (highlight the door to see it) if it's not obvious which side it goes on.
* '''Bind''' the handle to the door (bind <doorname>)
* It should now be a working handle though may need adjustments of rotation etc. see later.

Important: read preceding section on door handle types and performance issues first.

This works with both a model door and a brush door:

'''Rotation''':
* By default the door handle entity rotates ''anti-clockwise'' (looked at from the front) then springs back. A ''double handle'' model is OK but two singles (see ''Multiple door handles'' below) need more care as only one is the functioning entity and the other is just attached to it. So anti-clockwise is fine for a door with its hinge on the left and the handle on the right - the handle will rotate down then spring back. If you put the functioning door handle on the other side you will have to change the default ''rotate'' property from -45 0 0 to 45 0 0. '''''Therefore it is easier to generally put this handle on the side of the door where the hinge is on the left and the non-functioning attachment handle on the other side.'''''
*If your door only needs one handle, eg, a cupboard door, and from outside its hinge is on the right then you will need to change the ''rotate'' property of the handle as described above.

'''''The functioning handle entity:'''''
* Create an entity door handle (movers folder) or create a brush or model handle and assign it the entity ''atdm:mover_door_handle''.
* Position it where you wish on your door.
* '''Bind''' the handle to the door, by adding the "bind" spawnarg to the handle.

You now have a working door handle with default properties.

*'''Multiple door handles''':
Now that you've got a handle attached to one side of the door it is time to add one to the other side (unless you used a double handle).
* Create the new handle. The single handles come in left and right persuasions. A door needs a left facing handle on one side and a right facing handle on the other, so if you have already added the left handle create a right handle and line it up on the other side of the door.
* Name this handle. I prefer to keep a naming convention for each door and it's respective handles, it makes things alot easier. The door is named '''My_Door_1''', the first handle is named '''My_Handle_1''' so name the second handle '''My_Handle_1_1'''. This will make it stay with the first handle in the entity list. This is important to keep organized. If you name it My_Handle_2 then when you get to another door named My_Door_2 you'll be confused.
* Place and '''bind''' that handle to your door.

You now have two single door handles on either side of the door that rotate together as if they were physically attached.

'''To add a brush to a brush door''':
* Select the new brush ''and'' the brush door all together; ''the entity '''must''' be selected '''last'''.''
* Use {{menu|Edit|Reparent primitives}}. This ensures the parent entity adopts the new item(s).
* If you have trouble selecting them in the orthoview because other brushes, etc. get selected then try in the camera view or as a last resort move them temporarily to an open area (but keep them in the same positions relative to each other.) Use {{key-shift}}+{{LMB}} on new item(s) then {{key-shift}}+{{LMB}} on main entity. Once they are all selected, use the {{menu|Edit|Reparent primitives}}.

'''To add ''model'' static items''': knockers, hinges, static handles etc. to a ''Model Door'':
* Select item
* Right click in orthoview and select ''Create Entity'' then <code>entity func_static</code>
* Position it where you wish on your door.
* To synchronize this with your particular door you need to add the property ''bind'' and the individual door name to the brush entity. To do this...
** Select the model door.
** In the entity inspector, select the ''name'' line
** Select the bottom line in the input box ''below'' the properties window.
** Copy the name
** Deselect the door with {{key-esc}}
** Select the brush entity
** Add a property "bind" to it.
** Change the value of the property by pasting in the door name
** Click {{check}} or press {{key-enter}}

'''To add ''brush'' static items''': knockers, hinges, static handles to a Model Door:
* This method is not ideal but it seems to work OK.
* Select the brush.
* Right click in orthoview and select Create Entity then ''atdm:mover_door_handle''
* Position it where you wish on your door.

To synchronize this with your particular door you need to add the property ''door_handle'' on the door, and give as the value the name of the brush you just created.

This brush turns like a handle. To stop it:

* Adding ''rotate 0 0 0'' or disabling the handle script won't help.
* Add a real working handle (as in the section above ''To add a working model door handle...'' and it must be added LAST.)

If you don't want too see a real working handle added maybe try another tiny brush with the handle function and hide it inside the door?

===Locking Doors===

To lock a door check the ''show inherited properties'' in the entity inspector for a ''atdm:mover_door'' entity and you should see the ''locked'' property. Select it and in the input box below the properties you can change its value:

* 0 = unlocked (default)
* 1 = locked

If locked it will require an entity that is associated with it to be able to act as a key to unlock it.

Currently door handles on locked doors will rotate when frobbed, they will bounce back though and the door will stay locked until unlocked.

===Keys===

Assigning specific keys to specific doors is simple.

* It is recommended that you create an existing key entity. These keys have all required props, they just need to be named.

Alternatively you can create a key from the Model Viewer and want it to be useable
* Make sure it has the properties:
useable 1 [so it can be used by the door]
frobable 1
inv_name <unique name>
inv_category Keys
inv_target player1
inv_icon guis/assets/hud/inventory_icons/<icon name>
inv_stackable 0 or 1 where 1 can be used on all copies of the same key so they show as one entry in the inventory with a total.

Add to the door the property <code>used_by</code> with the name of the key as the value. Multiple keys can open the same door by using several <tt>used_by</tt> spawnargs:

"used_by" "doorkey_1"
"used_by1" "doorkey_2

==== Keys Carried by AI ====

So you have a door and you have a guard AI and you want the guard to be able to open/close/lock the door, but you also want the player to be able to pickpocket the key. Keys can be attached to AI in two ways.

''The Def_Attach Method''. This method is the best one for doors that you expect the AI to operate. It uses spawnargs to spawn the key at game start.

*"def_attach6" "atdm:prop_silverkey" // the entity to spawn - in this case a key.
*"pos_attach6" "belt_back_right" // where the key will spawn on the Ai.
*"name_attach6" "door_key" // this gives 'attach6' arg the name "door_key" and is the name the arg "used_by" will need, eg: "used_by" "door_key"
*"set inv_name on door_key" "Door key" // The name the key get when the play adds it to their inventory.
*"set name on door_key" "door_key" // here it gets a name to be used in the map in general.

For more info on this method, see [[Attaching Props to AI]].

''The Bind Method''. This lacks the animation finesse of def_attach, but does let you see the key in DR. The method is particularly helpful in, say, adding a second key to an AI in the back middle of a belt. The AI cannot use a bound key to open a locked door; the workaround is to fake it with "can_unlock" as discussed further below. Or to use bound keys mainly for items the AI will not attempt to open, such as hatches, duct covers, or chests.

* Load a key entity
* Position where you want it in relation to the AI, and bind it to them (i.e., "bind" "<AIname>")
* Add the spawnarg "bindToJoint" "Hips" (or another location like LeftHips_Dummy; see AI for list)
* Adjust existing spawnargs accordingly (that is, be sure the name and door's/chest's "used_by" match, if you aren't using a prefab chest with key). This is for the benefit of the player after pickpocketing the key; as stated above, the AI itself can't use it for unlocking.

For more info on this method, see [[Attaching_Items]] and [[BindToJoint]].

====Keys Carried by Player====

With a door's key selected in your inventory and the door highlighted, you can...
* unlock it (which will also auto-open if enabled) by either frobbing it or hitting the Use key (typically U or Enter).
* lock (or relock) it via the Use key. Why do this? To avoid pursuit, or to lure guards into a room, and then lock them in (if they don't have a key or specific can_unlock powers).

====Master Key for Testing====

By default, ALL locks can be opened by any key named ''key_master''. Just create a key in your map, name it ''key_master'' and it becomes a master key for use while testing. Add inv_map_start 1 to it so it is in the player inventory at game start. Remember to delete it when your mission is finished.

====Automatically Removing Keys from Player Inventory After Use====
If a fan mission has a lot of keys it can clog up the player inventory. If the key is single-use, it can be useful to automatically remove it from the player inventory after use. Below is a way to do it using a simple setup and a generic script function that can be used for multiple doors.

=====Generic Version=====

You'll need the following entities, preferably set up near each other in your map:
* The door entity itself
* A trigger_count entity
* An atdm:target_callscriptfunction entity
* some random entity for the target_callscriptfunction to target (explanation below)

The below diagram shows the spawnargs and targeting required for the setup:
[[File:Key remove2.png|left|thumb]]

<div style="clear: both"></div>
The script being called ('openDoor') is defined in fms/<mapname>/maps/<mapname>.script and looks like this:

void openDoor(entity target, entity door, entity callscriptfunction)
{
string keyName = door.getKey("used_by");
entity key = sys.getEntity(keyName);
$player1.replaceInvItem(key, $null_entity);
}

Explanation as follows:

'''For the door:'''
* '''trigger_on_open''' spawnarg: The door is configured to trigger its targets when it opens
* target '''trigger_count''' entity: this is the entity that is triggered when the door is opened
* '''used_by''' spawnarg: This names the key entity required for unlocking the door
* The other spawnargs are just the usual for setting the door as locked and unpickable

'''trigger_count entity:'''
* When triggered, this entity will in turn trigger the script that removes the key from the player inventory.
* '''count''' spawnarg: This is set to 1 because we only want the key removal script called once - the first time the player opens the door.
* this entity targets the atdm:target_callscriptfunction, which contains details of the script to execute

'''atdm:target_callscriptfunction entity:'''
* '''call''' spawnarg: This is the name of the script function to call
* '''foreach''' spawnarg: This version of the script event provides access to the 'activator', or the entity that triggered it (in this case, the door). Using that information we can obtain the key name. See [[A to Z Scripting: Ways of calling a script#target_callscriptfunction|here]] for details.
* '''target any static entity''': For this version of the script event to work, the target_callscriptfunction entity needs to target something. This can be any static entity in the map (i.e. one that won't get removed or anything). I usually just target the nearest entity (e.g. a light or a lamp, or a model). This provides no functionality in the context of this tutorial, it just satisfies the conditions of the script event.

'''The script:'''
* Pretty self-explanatory. The script gets the name of the key entity via the '''used_by''' spawnarg on the door, retrieves the key entity, and then replaces it in the player inventory with a null entity, effectively removing it.
* Any door can use this script as its generic (although they will need their own trigger_count and target_callscriptfunction entities)

=====Simpler, No-script Version=====
This is similar to above, but is more limited. You need to hard-code the key name as a spawnarg on an atdm:target_itemremove entity as they key name can't be automatically determined. This makes it slightly more error-prone as we're naming entities in more than one place, but ideal if you're uncomfortable with scripting.

[[File:Key remove3.png|left|thumb]]
<div style="clear: both"></div>

Explanation as follows:

'''atdm:target_itemremove entity:'''
* '''unique_item ''' spawnarg: The name of the key to remove from the player inventory

===Lockpicks===
''by Baddcog''

There are two lock pick types.
*'''s'''=snake
*'''t'''=triangular

A lock can be set with many pins. Each pin has a click sequence and each needs a designated lockpick type (see above). Keep in mind that the lockpicking in The Darkmod is much more involved than in T2 or T3. The player has to listen to sounds or watch a handle or lockbar to know when a lock is pin is picked.

This means that authors can be very evil and really frustrate the player, in which case their missions will probably not be played. So be nice to the player and don't waste your time. Use simple locks for the most part and save complicated locks for important sections and to build tension. Don't make the player have 20 pins to pick all with different lockpicks. In most cases 1 or 2 pins will suffice and it isn't necessary to use both lockpicks on every lock.
Also try to include a lock lever on lockboxes or chests, door handles will rotate as the pins are being picked. This gives the player visual clues to help with the picking (and essential in noisy environments where you can't hear the clicks.)
IMO this system is a huge leap foward for lockpicking but also has the ability to completely frustrate the player as stated above. Keep this in mind when designing your lockpick systems.

These props go on the door itself, or the lid of a chest, eg,
*'''lock_pins''' 1327
*'''lock_picktype''' stts

The lock_pins property specifies how many pins each lockpicktype has.
The lockpick_type property specifies how many times the player has to switch picks and which pick they have to use. You can see there must always be an equal number of lock_pins and lock_picktypes specified

So looking at the example above we have lockpick_type s(snake), t(triangular), t(triangular), and s(snake). The player will have to use these lockpicks in this order. Once the snake lockpick's pins are open the player can advance to the triangular pick and so forth.
5 is added to every click sequence so 5 is the minimum click pattern even if you set it to 0.
In the example above the lockpins specify in order which pick types have how many pins, so the s pick has 1 + 5 = 6 clicks, the t pick has 8 and so on.
The above is a difficult lock and to avoid annoying the player it is best only used rarely on a special lock like an important big vault door. Ordinary footlockers and common doors can be just 1 or 2 click sequences, eg, lock_pins 2 and lock_picktype t means the player uses one pick and listens for the end of one sequence of 7 clicks.

lockpick_rotate - is placed on the door. It is the amount the visible rotating handle or pin rotates while picking. For a rotating handle or lockbar normally ignore this and leave the default. During lockpicking it oscillates and progresses to the normal full turn of the handle. Example 0 45 0.

lockpick_translate - is placed on the door. It is the amount the visible handle or pin moves in a straight line while picking. Use this if you have eg, a lockbar that you want to move in a straight line and not rotate, eg sliding catch. Example 0 -5 0

By default, doors are pickable. If you don't set up the above lockpick spawnargs then it can't be picked. So there is normally no need to enable lockpicking - just set up the above spawnargs. There is a ''pickable'' spawnarg set to 1 by default. If set to 0 then the door becomes unpickable. But hard to think of an application except in testing or perhaps a special custom situation where it is switched by script perhaps.

===Open, Partially Open, or Closed Door at Game Start===

By default, doors are closed at game start. If you want a door to be already open or partially open then do the following.

'''Note well: Create all doors in their ''closed'' position. Adjust as follows and they will automatically be at the open position when game starts.'''

Already Open Rotating Door:
* Select the door.
* Select the entity inspector
* Check ''show inherited properties''
* Select the ''open'' property
* Edit the value to 1 in the input box below and tick the check button
* The door will now be fully open at game start.

* If you want it only partly open:
* Make sure its ''open'' property is set to 1 as above.
* Right click the entity inspector and select ''add property''
* Click the + sign on the left of the top line where atdm:mover_door is listed to open the folder. (if atdm:mover_door is not listed then the entity was likely changed from eg, func_static. If so, save the map and reload to update the add property list)
* scroll down, select ''start_rotate'' then click {{ok}}
* This adds it to the property list.
* Now select ''start_rotate'' in the property list.
* Edit the bottom line of the input box ''below'' the properties window to the angle you want in the same form as described in the ''Rotate Direction and Open Angle'' section. So for example, to have a door that has a fully open default ''rotate'' value of 0 90 0 to start only half open you would give it a ''start_rotate'' value of 0 45 0.
* In a similar way add the property ''first_frob_open".
* Set it to 1 and a partly open door should then open fully on the first frob.
* Set it to 0 and a partly open door should close on the first frob.

Already Open Sliding Door:
* Select the door.
* Select the entity inspector
* Check ''show inherited properties''
* Select the ''open'' property
* Edit the value to 1 in the input box below and click {{check}} or press {{key-enter}}
* The door will now be fully open at game start.

* If you want it only partly open:
* Right click the entity inspector and select ''add property''
* Make sure its ''open'' property is set to 1
* Click the + sign on the left of the top line where atdm:mover_door is listed to open the folder.
* scroll down, select ''start_position'' then click OK. (if atdm:mover_door is not listed then the entity was likely changed from eg, func_static. If so, save the map and reload to update the add property list)
* This adds it to the property list.
* Now select ''start_position'' in the property list.
* Edit the bottom line of the input box ''below'' the properties window to the position you want in the same form as described in the ''Sliding (Translation) Amount and Direction'' section. So for example, to have a door that has a fully open default ''translate'' value of 0 50 0 to start only half open you would give it a ''start_position'' value of 0 25 0.
* In a similar way add the property ''first_frob_open".
* Set it to 1 and a partly open door should then open fully on the first frob.
* Set it to 0 and a partly open door should close on the first frob.

===Rotation Centre, Pivot, Hinge point===

The centre of rotation of a door is at the origin point of its entity and the door rotates with reference to the orientation of that origin point, not the world map. See ''Rotate Direction...'' for more about that. This section only deals with the ''position'' of the rotation centre in the door.

Model Door Centre of Rotation:<br>
The centre of rotation of a model door cannot be changed within Dark Radiant. Because a model door rotates around the centre 'spine' of its back edge this will cause clipping (penetration into solid) as in this example (where the door is set to open to 89 degrees for clarity):<BR>[[Image:modelClipping.jpg]]<BR> So care is needed with placement. You will not normally position a door right next to a wall as in the example but against a shallow frame so clipping will barely be noticeable but either way it can be fixed. You can correct it by adding a translation (see ''Sliding (Translation) Directions'') value of half the door width in the direction of the door handle. This will gently move the door out as it rotates to clear any solid on that side as in this diagram:<br>
[[Image:DoorClip.jpg]]<br>
Half a door width will typically be about 2. Any 'attachments' such as door handles will still synchronize with the door movement whether the door is rotating, sliding, or both.

Brush Door Centre of Rotation:<br>
The centre of rotation of a brush door ''can'' be changed. The default origin point of a brush is at its centre. Therefore a default rotating brush door will rotate around its centre when you first create it. So, mappers will commonly need to move that rotation point to a corner or even to some other offset position for example, for an openable window using the door function.

Put simply, to move the rotation point of a brush door you need to move the entity origin relative to the brush(es.)

Moving the entity origin (centre of rotation) relative to a brush door:

* Select the brush door
* Select ''Vertices mode'' (default shortcut key is {{key|name=V}} or button on top toolbar 'Select Vertices')
* Drag the door's entity origin to the point where you want the door to rotate. This should be on the corner on the leading edge side (the side to where the door is opening.) to avoid clipping as in this diagram....
[[Image:getCorner.jpg]]
* You should now find that door rotates around that point.

===Rotate Direction and Open Angle===

By default, rotating doors open anti-clockwise (viewed from above) by 90 degrees from the start orientation. If you want to change this edit the ''rotate'' property in the entity inspector. Don't confuse this ''rotate'' property with the ''rotation'' property. In the entity inspector remember that to see the inherited rotate property you must check the box 'Show inherited properties'.

The three values shown in the rotate property are degrees from the closed position around Y Z X (absolute map axes Front, Top, Side views in DR's ortho view.)

* Positive Y = Open clockwise (Dark Radiant grid front view, looking north)
* Negative Y = Open anti-clockwise (Dark Radiant grid front view, looking north)

* Positive Z = Open anti-clockwise (Dark Radiant grid top view, looking down)
* Negative Z = Open clockwise (Dark Radiant grid top view, looking down)

* Positive X = Open anti-clockwise (Dark Radiant grid side view, looking west)
* Negative X = Open clockwise (Dark Radiant grid side view, looking west)

There is a problem when you come to rotations that are not around the main Y Z X axes of the map, for instance a drawbridge that lowers down to the south east. You might think you can combine Y Z X values to get the result you want - and this can be done (for south east use 45 45 90) but it is a bit of a kludge and the drawbridge twists eccentrically as it lowers (though it arrives correctly!)

The values are in the range -179 to +180. Positive values give an anti-clockwise opening rotation (looking down from above) and negative values give a clockwise opening rotation. The value 180 is unique in that it continues in an anti-clockwise rotation when closing rather than returning clockwise so might be used if you can think of some object that might need such a motion when frobbed!

Edit the rotate value by selecting it and using the input box at the bottom and clicking the check(tick) button. That will change the angle the door will open to. Note that the line with the original default of 0 90 0 will still be there but your new entry will be added on a separate line and that is the one that will work in the game. CAUTION: when adjusting later make sure you have your new line selected and not the original! If you do it will appear to change but your first setting will remain unaltered.

Examples:
* 0 90 0 = Opens anti-clockwise round the entity's 'vertical' to 90 degrees - typical default vertical door.
* 0 0 90 = Lowers a drawbridge from the entity 'vertical' to horizontal.
* 0 0 -45 = Opens clockwise by 45 degrees viewed from the east side. This might suit a skylight in a sloping roof.

'rotate' cannot be combined with translate motions (see [[#Sliding (Translation) Amount and Direction]]) in one door; you need to bind one door to another and link they by targetting one to the other. By that means you can produce exotic and useful motions. A door opening against an upward-sloping floor can thus have a ''lifting hinge'' and raise up slightly to clear the floor; a door can rotate towards you and slide back to one side very effectively.

===Sliding (Translation) Amount and Direction===

By default a Dark Mod door will rotate open. For most sliding doors you want to stop them rotating as well as make them slide. You cannot delete (remove) the ''rotate'' property - you have to set the ''rotate'' property to 0 0 0 to stop a door rotating (see ''Rotate Direction and Open Angle''.)

Now edit the ''translate'' property value by selecting it (remember to have inherited properties box checked) and using the input box at the bottom and clicking the check(tick) button. That will change the distance the door will slide to. Note that the line with the original default of 0 0 0 will still be there but your new entry will be added on a separate line and that is the one that will work in the game. CAUTION: when adjusting later make sure you have your new line selected and not the original! If you do it will appear to change but your first setting will remain unaltered.

Typically (but not always) you will want your sliding door to slide the width of the door. The three values in the translate property by default are 0 0 0 and are X Y Z ''absolute map'' values (irrespective of door orientation) where:

* Positive X = Slide East (Right side of Dark Radiant grid in top view)
* Negative X = Slide West (Left side of Dark Radiant grid in top view)
* Positive Y = Slide North (top of Dark Radiant grid in top view)
* Negative Y = Slide South (bottom of Dark Radiant grid in top view)
* Positive Z = Slide Up (Top of Dark Radiant grid in side views)
* Negative Z = Slide Down (Bottom of Dark Radiant grid in side views)

So for a 50 unit wide door you want to slide fully to the east you would use 50 0 0 for the translate property values. A 100 unit portcullis sliding vertically up would need 0 0 100 to be fully raised.

=== Doors Collision/Push Behaviour ===
Doors push all entities by default, except for the player. Doors will also stop moving when anything blocks their movement. However, this default behaviour can be changed by setting appropriate spawnargs:

Set '''push_player''' to '''1''' to let the player be pushed by this door:
"push_player" "1" // Push the player too (default is off)

By default '''stop_when_blocked''' is set to 1 and if a door is blocked by an entity then even if the entity is removed afterwards, the door stays where it is. The next frob will close the door.

Set '''stop_when_blocked''' to '''0''' to prevent the door from ending the opening sequence when anything blocks its way. It will still pause - but continue to open if the block is removed.
"stop_when_blocked" "0" // door keeps moving after being blocked (default is off)
With this setting, doors will still stop at blocking entities (the player, for instance), but will continue to move when the entity moves out of the way.

There is another spawnarg which stops a door pushing a moveable. Apply this to the ''moveable'', not the door...

"notPushable" "1"

===Door Sounds===

There are multiple ways to put sounds on doors.

''snd_open'' <br>
Sound is triggered as the door begins to open.

''snd_opened'' <br>
Sound is triggered when the door finishes opening. Defaults to "nosound".

''snd_move''<br>
The sound plays while the door moves. Defaults to "nosound".

''snd_close'' <br>
Sound is triggered as the door finishes closing.

The following sounds should be left on the default sound in most cases so players clearly know what is going on:

''snd_locked''<br>
The sound played when a player or an AI tries to open a locked door.

''snd_unlock string''<br>
The sound played when a door is unlocked.

You can silence any of these sounds by setting the following properties as shown:

''snd_open nosound''<br>
''snd_close nosound''

Don't just use a dash - as it seems to cause a sound of its own.

===Sound Propagation through Doors and Doorways===

''This information will change significantly with the release of 2.0. See'' [[Controlling Sound Loss Across Portals]]

The sound volume reduction to the player (ie, the sound the player hears) is fixed and constant in a cvar which adds a distance factor to the original sound. It is recommended that you do not change that because it will affect other FMs. Currently there is no way to change the way that sound to the player is reduced through doors and doorways.

Sound propagation to AI, eg, impact sounds or guard yells is treated separately:

Sound propagation to AI relies on visportals. For details study [[Sound Propagation: Part 1]] and [[Sound Propagation: Part 2]] as well as [[Visportals]] This tutorial will just cover the relevant sound and sound propagation ''properties'' of doors. If you set the ''show inherited properties'' box in the entity inspector you can see them as described here.

Remember, the following have no effect on what the player hears through a door or doorway.

''loss_open''<br>
Drop in sound volume in dB propagated to AI (not player) when going through an open door. (default 1dB)

''loss_closed''<br>
Drop in sound volume in dB propagated to AI (not player) when going through a closed door. (default 15dB) You would want to set this very high to block all sound with a thick door but very low for a barred gate for example.

''loss_double_open''<br>
Drop in sound volume in dB propagated to AI (not player) when going through double doors when only one is open. (default 1dB)

There are also various sound properties for lockpicking:<br>
''snd_lockpick_pin_1 through 14'' and ''snd_lockpick_pin_success''

===Allowing the Player to Interrupt Door Motion===

The door property ''interruptable'' determines whether a door can be stopped by frobbing while it is opening or closing. It is enabled (i.e., set to 1) by default. Then the player, by frobbing to start the normal opening, then frobbing again to interrupt, can open a door to any position, e.g., slightly ajar to peek through. Another frob will begin closing, and so on with any additional frobs to stop/reverse-direction.

Be aware that an rotating-style door, when left ajar, will subsequently open or close more slowly than normal in an angular-velocity sense. It instead takes the same time as a full (uninterrupted) opening or closing would take in seconds, as given by ''move_time'' discussed next.

===Speed of Door Opening and Closing===

Rotating Door Speed:<br>
The time a rotating door takes to open or close is set in the ''move_time'' property, no matter what its maximum open angle may be. So with rotation set at, say, 150 degrees the door just opens faster than at, say, 80 degrees. To change this value, make sure the door is selected then...

* Right click the entity inspector and check ''show inherited properties''
* Scroll down, select ''move_time''
* Edit the second line of the input box ''below'' the properties window to the time you want.
* The time is in seconds and decimal fractions can be used. The default is currently 1.75 seconds.

Sliding Door Speed:<br>
The speed of a sliding door is set in the ''translate_speed'' property. To add this, make sure the door is selected then...

* Right click the entity inspector and check ''show inherited properties''
* Scroll down, select ''translate_speed''
* Edit the second line of the input box ''below'' the properties window to the speed you want.
* The speed is in Dark Radiant grid units per second.
* The default is 0 and if set to this then the door slides open in one second whatever the distance, great or small.
* CAUTION: It is assumed ''translate'' has been changed from its default value of 0 0 0. If not, a non-zero ''translate_speed'' may cause problems.

===Visportals and Doors===

A visportal face surrounded by solid at its edges and in contact with a door is closed when the door is closed and enabled when the door is open. In most cases you will place a visportal in contact with a working door unless you can see through the door (such as a true glass door or barred gate*.) For full details see [[Visportals]].

''*As of 2.0 it is possible to make visportals that remain transparent when closed for gates and windows. See'' [[Controlling Sound Loss Across Portals]]

==Auto-Closing/Opening Doors==
Doors that automatically close after being open for some time are easy to setup: Each frobmover entity supports these spawnargs:

;"auto_close_time":Set this to something >= 0 to let the mover automatically close (again) after this time when being fully opened (measured in seconds). Defaults to -1, which means 'do not autoclose'. The event is also activated when the mover starts at the open position at map start.
;"auto_open_time":"Set this to something >= 0 to let the mover automatically open (again) after this time when being fully closed (measured in seconds). Defaults to -1, which means 'do not autoopen'. The event is also activated when the mover starts at the closed position at map start.

<div class="toccolours mw-collapsible mw-collapsed">
Before auto_close_time and the AI Door Management spawnargs next were provided, a more laborious method was used to auto-close doors as if AI were closing doors behind them. Hit "Expand" to review it.
<div class="mw-collapsible-content">I have one door that I particularly want the AI to close as there is a bit of frame lag inside if not. So I set this up and it works good as an auto-closing door - not as good as a true AI closing door as it will auto close when the player goes through as well but it does look very effective to see AI going through and closing the door behind them. Not tested exhaustively so I don't know if there could be any downside. Here's what to do....

First a quick summary to make it more clear:

'''''A trigger_relay is used both as a relay AND carries a stim. We put the trigger_relay with its stim in the path of the open door. The door has a response property. When it opens and contacts the stim its response is to send a signal back to the relay. The relay pauses then closes the door...'''''

* First, optionally give your door a suitable name like autodoor1, whatever.
* Copy that name to the clipboard.

Next we need a relay with a delay:

* Create entity > darkmod > trigger_relay

* Place it roughly at the position the door will be at when open and to be on the safe side 3/4th of the way to the far end of the door (not the hinge end) to give max distance from the close door.

* Add the property 'target' and paste in the door name you just copied.

* Give the relay itself a name, eg, autoDoor_relay_1, and copy that name to the clipboard, you'll need that too in a bit.

* Add the property delay and the value 3 - this is the delay in seconds before the door will close; 3 seems about right but 2 might be worth a try because to that 3 is added a random value between 0 to 0.5 seconds from the Time Interval we entered for the stim firings.

* Add the property 'wait' and the value 3. This is the time before it can work again in seconds. If you set it too low then in theory the door might trigger again but in this situation I don't think it's possible. Too long, eg, one minute, and it won't work if the AI goes back through the door before then. If this value is -1 then the whole thing will only work ONCE so might be used for an AI who goes through once, closes it behind him, but you don't want it to be an autodoor thereafter.

That's the relay, now we add a stim to it:

* Still with the trigger relay selected, go to {{menu|Entity|Stim/Response}}

* Custom stim tab.

* Click Add stim type, select the new custom stim type you just made at the bottom of the list and type in eg, autoDoorStim at top right in the input box.

* Click the stim tab and the little drop down arrow against the 'type' selector at bottom left and you should see your new custom stim name. Select it.

* Select the new autoDoorStim in the list and on the right you need only type in the radius box 15.0 There is quite a lot of room for error. I had it working on 10 and also on 25. The value should be less than the distance to the closed door else it will trigger open! But no so small that the door might not reach it.

* Select the check box for Time Interval and enter 500 (millisecs.) This is so it doesn't keep firing more frequently than is necessary. This stim will be firing all through your mission whether the door is used or not so if you had dozens of these then maybe it would affect performance. Too big a number and there may be a long delay before the door shuts - but it will be random depending on the next time the stim happens to fire. We'll control the delay we want more precisely later.

* Click {{ok}} to confirm it.

That's the stim set up, now for the response to it which is put on the door....

* Select the doorm, then use {{menu|Entity|Stim/response}} and select the response tab.

* Click the little drop down arrow against the 'type' selector at bottom left and you should see your new custom stim name. Select it.

* Right click in the big ''Response Effects'' box on the bottom right of the panel.

* Add New Effect and you should get a default 'Activate Response' response added to the list. Double click it.

* In the Effect selector at the stop select 'Trigger'

* in the Target box, paste in the name of the relay you copied or you can select it from the list at the little arrow.

* Leave the Activator box empty.

* Click {{apply}} and then {{ok}} on the main S & R panel bottom right.

It should now work. No need to wait for an AI, just frob the door and watch it close itself. If not, check the position of the stim brush is close to where the door stops when open.</div>
</div>

==AI Door management==

By default AI will open doors and close them behind them. Here are some spawnargs '''on the door''' the mapper can use to modify that behaviour:

;"ai_should_not_handle" :If set to 1, AI will not attempt to handle it and add it to the forbidden areas (so that it doesn't try to path through). They might still walk through the door when it is open though. Useful if you have some special use door that you don't want the AI to operate.

;"ai_should_not_close" :If set to 1, AI will not close the door behind them unless it obstructs them.

;"canRemainOpen" :If set to 1, it's the same as "ai_should_not_close, with the added behavior that this is ignored if the door needs to be relocked, or the door is marked "shouldBeClosed". '''(This spawnarg is available starting in TDM 2.02.)'''

Spawnargs '''on the AI''' that the mapper can use:

;"canCloseDoors" :Added in 2.12. Defaults to 1. If set to 0, the AI will not close doors after passing through them.

To get AI to unlock/relock specific doors there are two methods:

1. Provide the AI with the key, as detailed in the def_attach method in [[#Keys_carried_by_AI]] above.

2. Add the following spawnarg/value to the AI:

;"can_unlock" ''<doorname>''

For additional doors on the same AI use ''can_unlock1 doorname', `can_unlock2 doorname' etc. '''Do NOT use can_unlock_1.'''

If both (1) and (2) are used, then the AI can still go through the door after the player pickpockets the key. Otherwise, unless someone else opens the door for the AI, a typical sequence is that the AI checks their pockets for the missing key, stalls a bit at the locked door, and then (with now-better pathing algorithms) the AI uses an alternate route to the next path_corner, or "mentally" skips ahead in the route to next reachable node and goes there.

===Door Handling Positions===

It is also possible to set custom door handling positions for the AI. This is especially useful when the standard routine that lets the AI choose their standing positions while opening and closing the door fails, leaving them standing still, or circling around in front of the door helplessly.

Place a movers > ''atdm:door_handling_position'' entity where you want the AI to stand while opening/closing the door from this side.

On the door, you need to set the spawnarg "door_handle_position" "name_of_door_handling_position". You can also place a ''door_handling_position'' on each side of the door, and the AI will automatically choose the right one. In this case, you need to set spawnargs with "door_handle_position_1" etc., and the corresponding names of the ''door_handling_position'' entities on the door.

The ''door_handling_position'' entities can also carry spawnargs that define the behaviour of the AI, which are useful for example for doors that can only be opened or locked from one side:

'''"ai_no_open"''' If set to "1", the AI will not try to open the door from this side (but will still walk through when the door is already open).

'''"ai_no_close"''' If set to "1", the AI will not attempt to close the door from this side.

'''"ai_no_unlock"''' If set "1", the AI will not be able to unlock the door from this side, but still use it when it is not locked.

'''"ai_no_lock"''' If this is set "1", the AI will not lock the door from this side.

===Door Controllers===

'''Available in TDM 2.02+'''

You can design a door so it's operated by buttons or levers or switches (aka ''controllers'').

A controller is simply an entity that targets the door. Typical examples of entities that can be used are:

* Buttons: atdm:mover_button
* Levers: atdm:switch_rotate_lever
* Switch: atdm:mover_lever
* Lock: atdm:froblock. (See also next section)

1. Set up the door in the normal manner. It can be a rotating door, a sliding door, a locked door, etc.

2. Turn off the "frobable" spawnarg on the door. ("frobable" "0")

3. Create a controller entity on each side of the door. If you're setting up a locked door using atdm:froblock, there's no need to put any locking information on the controllers. When the game starts, it will transfer any locking information from the door to the controllers.

4. Give each controller the door as a target.

Both the player and any AI that wants to use the door will use the controllers to operate it. Any key, "can_unlock", or lockpick settings you would normally use at the door are now used at the controllers.

Controllers and ''door_handling_position'' entities can be used on the same door, but in that situation the ''door_handling_position'' entities don't define where the AI stands to operate the door. They simply provide the "ai_no_*" spawnargs that define AI behavior on each side of the door.

If you wish, you could provide a controller on only one side of the door instead of both sides. Note that, since the door is not frobable, the player won't be able to operate the door from the non-controller side.

====More about Using a Separate "Froblock" Lock Plate====
''by Geep, 2021-22''

Froblock, just discussed as a controller method, actually predated the controller concept in TDM. Here we recap that earlier context, with an alternative treatment of highlighting, and thoughts on texturing and usage.

Suppose you want to have a lock plate (typically mounted on a door frame or wall) that opens a nearby door, where the door and lock plate highlight separately. A traditional way is to adapt the ''froblock'' method described under the "Making your own" section of [[Containers, Chests, etc.]]

Basically, your door is the "chest lid" (of class atdm:mover_door) and your lock is the "chest body" (of class atdm:froblock). Set the properties as described in the wiki. There is a stock texture (darkmod/door/keyhole_metal_001) you can use to decorate a surface of your lock plate, or a patch on it. This method is probably most apt for small hatches and grates designed for the player alone, and with no handles, or non-turning handles attached with "bind".

===AI and 'non-frobable' Doors===
Be aware that the 'frobable' spawnarg only applies to the player, not AI. If you set a door to be non-frobable (i.e. 'frobable' '0'), AI can still operate it by interacting directly with it, even if it has a controller. For example they will do this if:

* they are fleeing or chasing the player
* the door has a controller but the AI can't reach it (for example the controller is on the other side of the door)

The best way to mitigate this is to use Door Handling Position entities (see above) with the 'ai_no_open' spawnarg set on them.

===AI locking doors behind them===

If one AI is involved (no one else is in the queue), he'll lock it behind him if he had to unlock it in the first place.

Prior to TDM 1.08, if more than one AI is using the door at the same time (there's a queue), the first AI unlocks the door, and the last AI through will only lock it if it's marked "should_always_be_locked" AND they have a "can_unlock" for that door or they have a key for that door. The last AI to use the door doesn't know that the first AI found it locked, because that info is kept per AI, and not per door.

Starting in TDM 1.08, if the first AI in a door queue found the door locked, that information is remembered by the door and the last AI through uses it to relock the door, as long as they have a "can_unlock" for that door or they have a key for that door.

In the rare case where a door is set up to use door-handling position entities (necessary for AI to use sliding doors), either or both of those entities can have the "ai_no_lock" spawnarg, which means AI aren't allowed to lock the door from that side.

==Initially Blocking a Door - Partially or Fully==
''by Geep 2021''

Suppose you have a door that you want to start out either as unopenable, or able to open just a crack, then later, after something happens, be fully openable and operational. One method known to work:

* Create a moveable object that the opening door runs into and tries to push.
* Arrange that the far side of the moveable object is jammed against some immovable worldspawn.

Here's two specific examples that use a wooden plank moveable:

* In "Perilous Refuge", a plank blocks the door leading out of the player's starting location, until the player carries it away.
* At the end of "Away0" (WIP 2021), the player tries to open a door. But if preconditions aren't met, the occupant seems to let the door open only a crack and complains. Blockage is done by an unseen plank resting on the floor hitting a knob of worldspawn. Preconditions met causes a "$plank.remove()" script call.

Other methods that you might think would work but don’t:

* Block with a func_static object, or an unjammed moveable with "notpushable 1" set. In both cases, the door travels through the object.
* In advance, "grab" an unjammed moveable to make it appear "solid" to the physics engine. (This was tested by having the player manipulate it; if it had worked, a “grabber” script call might suffice.)
* Dynamically change the door’s "rotate" limit from script using "setSpawnArg"; this function would only work before you spawn the door, not afterwards.

(Others possibilities not yet tested:

* Change "rotate" using the "setKey" script function; for some spawnargs this works even after spawn.
* Create a moveable and bind it to the world entity.
* If you are mainly interested in initially blocking an AI from using a door: it's possible that the AI re-reads the spawnargs for what doors it's allowed to open. Try adding a frob Response to the key (Entity -> Stim/Response... -> Response) with an effect that sets the “can_unlock" spawnarg on that AI to "-".)

==Controlling a Door by Scripting==
''by Geep 2021''
===If Unlocked===

Simply use, for example with a door named ''door1'':

$door1.Open();
...
$door1.Close();

Alternatively, toggle it open or closed with:

$door1.frob();

If the door has "interruptable 1" (which is the default with atdm:mover_door), you can also frob() it twice to leave it ajar. Interpose and adjust a sys.wait(...) to tune it.
===If Locked===

You need to unlock it first. Changing the door's "locked" spawnarg value won't work. Instead you will use:

$door1.Unlock();

But there are complications. By default, the door has spawnarg "open_on_unlock 1". So, assuming you didn't change that, you'd think unlocking the door would open it. But this spawnarg will be ignored if the gamer has global menu option "Open Doors on Unlock" set to Off. Assuming you want to reliably have the door open, do this:

$door1.Unlock(); // MAYBE will open door too.
sys.wait(3); // If so, wait for door to fully open. Value may need adjusting based on door's speed
$door1.Open(); // Otherwise, open it now.

The wait is added, because otherwise, the opening begun by Unlock may be stopped by Open with the door only partially open. (Probably an alternative to using sys.wait here is to zero the door's "interruptable" spawnarg.)

==Doors as Triggers==

''by Ishtvan & greebo''

Doors (or any binary frob mover, buttons, levers, etc) now have the option to [[Triggers|trigger]] their target on closing or opening. (For definition purposes, a button is defined as "closed" in the state when it starts out and "open" in the state you press it down to. I know that's a little non-intuitive, but it came from deriving from doors).

New spawnargs on frob movers:
;"trigger_on_open" :If set to 1, this binary mover will trigger its targets when it starts out completely closed and is opened.
;"trigger_when_opened":If set to 1, this binary mover will trigger its targets when it is completely opened. Code defaults to 0.
;"trigger_on_close":If set to 1, this binary mover will trigger its targets when it completely closes after being open.

== Suspicious Doors ==

If you give a door the spawnarg '''"shouldBeClosed" "1"''', then AI will treat it as suspicious if they find the door open.

Doors with that spawnarg should work like this:

- an AI opening the door knows he's not to become suspicious if he opened the door

- nearby AI alerted by the open door will also not react if they can see the door, and can see the AI that opened it

- AI who come upon the open door later probably won't be able to see the AI that opened it, so they'll treat it as suspicious

- if the AI who opened the door comes upon the door later, and it's still open, and no one's touched it since he opened it, he'll see his name on the door and won't become suspicious. "Oh, crap. I forgot to close it earlier."

- If an AI comes upon an open door that should be closed, he should close it whether he becomes suspicious or not.

'''Post TDM 2.00:'''
- AI turn to look at a door they see opening. The player can crack open a suspicious door to peek out w/o grabbing the attention of a nearby AI. After 5s, the AI will notice the cracked open door. Non-suspicious doors can be cracked open indefinitely w/o nearby AI noticing.

==Slanted or Tilted Doors==
Slanted or tilted doors can be made as follows:

1) Place your door, preferrably one of the prefab doors, which have a model door and model handle and all the rotation spawnargs pre-set.

2) rotate and place the door+handle model into place you want it to be. Now, if you use the door in the game, the door will rotate around the world z-axis, and not the door model z-axis (which is rotated).

3) to get the door to rotate around the door model z-axis, you must place a model (any model will do, and it can be placed anywhere in the map). Rotate the new model into the same orientation your door model was rotated, i.e. if you door is rotated 45 degrees around the x-axis, do the same rotation on the new model.

4) bind the doors on the new model. This makes the doors start rotating along the new model origin (which is rotated the same way as the doors).

5) working slanted door.

Do note, that all the rotated objects need to be models (suspicion, not tested). You can export DR built stuff into a model using the DR ase exporter script. For custom doors, remember that the exporter places the model origin at the map origin if you do not choose the "place origin in the middle of the object" option.

Also note that the AI probably cannot use slanted doors and might get stuck (suspicion, not tested).

There is a link to a test map here:
http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/?p=395486

==Skins: A Wide Variety of Door Textures==

This is to remind you that as with many Dark Mod models, there is a wide range of extras skins (textures) available for door models. There are now several basic door entities of different sizes so choose your size first. Then enter the spawnarg: skin with any temporary value. Now select it and click the skin button at the bottom of Dark Radiant's Entity Inspector and you will find a large of range of skin textures from which to select to give you a choice of appearances for your door.

==Extra Notes==

''func_darkmod_door'' is no longer used (just in case you come across it in the Dark Mod forums or wiki.) '''<code>atdm:mover_door</code>''' is the entity to use.

{{tutorial-editing}}

File:Key remove3.png

2025-11-06T20:00:40Z

Frost Salamander:

diagram showing key removal entities

Doors

2025-11-06T19:47:06Z

Frost Salamander: /* Automatically Removing Keys from Player Inventory After Use */

{{todo}}
''Written by Fidcal'' ''edit Baddcog''

==Quick Summary==

Quick way to get an unlocked door in your map:

* Insert one of the prefab doors complete with handles and select its skin property and click the button to change its skin appearance to whatever you want. Set any other properties you need.

Alternatively,

* Create a door from the entity list
* Use the "skin" spawnarg on the door to change its appearance.
* Create a handle from the entity list
* Add the ''door_handle'' property to the door and give it the name of the handle
* To the door handle add the value frob_peer and use the name of the door.
* To open clockwise, change the ''rotate'' property from <code>0 90 0</code> to <code>0 -90 0</code>

==Introduction==

This tutorial explains how to put doors into your map using Dark Radiant, as well as adjust them and their properties.

The rest of this tutorial assumes that you have a basic understanding of using DarkRadiant. If you haven't done so, please go read the [[Dark Radiant Must Know Basic Intro]] article first.

Additionally:

* Up, down, right, and left in Dark Radiant's ''top'' orthoview are regarded here as the standard map directions of North, South, East, and West where useful for clarity.
* Where the term ''brush'' is used with a door it mostly also applies to a door made up of a group of brushes and/or patches.
* Where the term ''door'' is used it often will also apply to any object you wish to rotate when frobbed, for instance an openable window, box lid, or even more exotic objects that the imaginative mapper might conceive like a signal, engine part, toy, or whatever. So long as it needs to turn or slide just a fixed amount when frobbed then return when frobbed again then the following applies.

==Door types==

All tangible objects in Dark Mod are ''entities'', having either a pre-made model shape or else brush/patch(es). So there are two ways to create a door in Dark Radiant: as a model door or a textured brush door (or a hybrid of the two).

Models are ready made door objects but cannot within Dark Radiant (at the time of writing) be resized, rescaled, cropped or clipped whereas brushes are very flexible in that respect and can be worked into custom shapes for your map, including secret doors that blend into walls and other surfaces.

Most of the current door models are found in two places along with the door handles.
*Model Viewer: doors created from here will be static in the world and have no props other than material type.
You can add any props to them to make them working doors. If nothing else it is a good place to view the different size and skin options for the doors.
*Entity List: most of the door models can be found here. These doors have properties already assigned so they are ready to be used. Only one base door of each type is listed, create the size/hinge count door you want (2 hinge doors have a 'no hinge' skin). You can choose a skin for the door once it has been created in the editor with the "skin" spawnarg (use the model name of the door you want, taken from the model list, as its value). This is the easiest way to create a door. The same goes for door handles.

Remember also that door functions may be applied to objects other than doors, such as openable windows, drawbridges, gates, etc. In fact, anything that needs a partial rotation or slide when frobbed then return when frobbed again, such as a signal device. Lockboxes and chests use similar properties.

You can create one door/handle set and copy/paste it, but you need to take great care that all the name props are changed to match in each clone. Otherwise you get handles that fly off when a distant door moves, and handles that don't move.

==Creating a Door==

Put simply, to make a door you will be creating an 'entity with model' or 'entity with brush' or some variation thereof.

===Creating a Model Door===

There are several approaches to making a model door; the simplest is to create a door from the entity list; or create a door from the model viewer (good for static unusable prop doors).

'''Entity List''':

*Deselect everything in editor by hitting the Esc button
*Right-click an ortho view and select Create Entity
*Navigate to darkmod/movers/''atdm:door_...'', choose the door you want
*Click Add
*To change its appearance, add a "skin" spawnarg to the door, with the value being the model name of the door you want.

You now have a workable door in your level.

'''Model Viewer''':

* Right click in the orthoview, select ''Create Model'' then <code>darkmod</code> and select a door.
* Note that you can left drag the image in the ''Choose Model'' dialog to rotate it around.
* Click [[Image:Button ok.png]] and you have a static door.
* If you want to make it work (openable, frobbable) then:
** Select the entity inspector,
** Select the top classname line so it highlights
** Select the func_static line in the input box ''below'' the properties window.
** Edit <code>func_static</code> to <code>atdm:mover_door</code>
** Click {{check}} or press {{key-enter}}

Alternatively you can do it the old way:

* Create any temporary brush
* Right click in orthoview and select <code>Create Entity</code> then <code>atdm:mover_door</code>.
* Left lick the model name line in the entity inspector.
* Below it on the ''Entity Inspector'' panel you should now see a button 'Choose Model'
* Left click it, select a door model from the darkmod group.
* Note that you can left drag the image in the ''Choose Model'' dialog to rotate it around.
* The temporary brush was deleted.

In all three instances, you now have a working door with default properties.

Name your door by adding the prop (or modifing it) to name ''My_Door_1''. You can use any name that you feel is appropriate but all doors with handles attached ''must'' have their own specific name. Use the name My_Door_1 for your first attempt as it will be referenced when you get around to attaching handles (see below).

To add a handle and other adjustments, see [[#Customising and Adjusting Door Properties]] below.

===Creating a Textured Brush Door===

'''Tip:''' If unsure of size then you might insert a temporary human AI first to get a sense of height.

==== The simplest brush door: ====

* Drag out a new brush to the size required, eg, a seven foot high door is 84" x 1.1 = about 90 units in Dark Radiant.
* Give it a door texture from the texture browser (or wall texture for a secret door)
* Right click in orthoview and select ''Create Entity'' then <code>atdm:mover_door</code>

You now have a working door but it will rotate around its center. To move the rotation point to where you want the door hinges to be:
* Select the door and press 'v' or the ''Select Vertices'' button to enter vertex editing mode. The door's origin will show up as a small green square in the middle of the brush.
* In top-down orthoview, move the origin from the center to the corner of the brush. This is easiest in drag mode ('q' or the ''Resize'' button), although you can use translate mode ('w' or the ''Translate'' button) by manually selecting the vertex first.

==== Multi-brush doors: ====

More complex multi-brush doors can be created using the [[Clipper]] tool, CSG, etc. - this is not covered in this tutorial. Then assign <code>atdm:mover_door</code> for that whole brush structure. Also you can collect various brushes positioned together in relation to one another as needed, select them all, then assign <code>atdm:mover_door</code> for the group. All the brushes will be children of the <code>atdm:mover_door</code> entity and will rotate and be frobbable, etc. as one unit, as one door. To add further brushes or even model shapes later see the section on [[#Adding handles and other items to doors]].

Name your door by adding the prop (or modifing it) to name My_Door_1. You can use any name that you feel is appropriate but all doors with handles attached must have their own specific name. Use the name My_Door_1 for your first attempt as it will be referenced when you get around to attaching handles (see below). (repeated from above in case you didn't choose to create a model door)

=== Double Doors ===
Double doors are automatically recognised by the code when the doors are spawned. The prerequisite is that both doors are sharing/touching the same visportal. The spawnarg ''auto_setup_double_door'' (which defaults to "1") will take care of setting up the open/lock peer relationship between the two doors. The doors will open/close and lock/unlock along with each other as a result.

What happens behind the scenes: the doors are adding each other to their internal open_peer and lock_peer list, which causes the double doors to perform the same action when frobbed or used.

Note that ''auto_setup_double_door'' will not set the frob_peer relationship, i.e. each door will frob-highlight on its own without highlighting the other door. You'll need to add that spawnarg manually if you want to highlight the entire double door as one.

==Customising and Adjusting Door Properties==

Handles, lockplates, etc. can be added to doors and door properties can be adjusted for rotation, sliding, locking, and more.

Some of the door models have hinge plates and lockboxes that are reskinnable with a good variety of skins.

===Door handles and other door attachments===

'''Summary: just add the property ''bind'' with the door's name to the attachment and position it where you want it on the door. If it's a ''atdm:mover_door_handle'' then it automatically will work as a handle but you can bind virtually anything.'''
You can add handles and other items to doors such that they move correctly with the door whether rotating, sliding, or both and even if the door is not vertical such as a skylight or trapdoor.
Handle models come in two types, ''single handles'' and ''double handles''. A single handle is one sided, this means the handle will be inside the door or outside the door, but not both. A double handle has a lever on the inside of the door and a handle on the outside of the door. Each has benefits.

*'''''Single door handles''''':
Single door handles can be used on a static door, a door that's just for show that no AI's or the player can use. In this case you should just create a door handle from the model viewer, it will be static and have no properties such as scripts. It is for looks only. Note that TDM is trying to establish the expectation that decorative doors that cannot be opened do not have handles (though not all maps follow this).

I will call this ''multiple handles'', see more below.

These can also be useful on brush doors created in the editor that may be very thin or very wide.

*'''''Double door handles''''':
These are models have have a handle inside and outside. The bonus is that they only use one entity. Maps are limited to about 4,000 entities but when you count lights, AI, sound speakers, ect... you can run out of entities quickly on a large map. If you plan on building a large map this is the way to go, even in a small map they have benefits, namely that you only have to attach one handle per door.

Whether you decide to use a single handle or a double handle you must first follow the instructions below and attach one handle first. If you choose a double handle, follow the instructions below and you are done. If you choose a single handle type follow the instructions then also follow the ''multiple handle'' instructions for the second handle.

Both single and double handle types can be found in two places. The model viewer which will create a static model good for show, you can manually add props to make them work OR you can look in the entity browser.
Using a handle from the entity browser saves you a little bit of time as some props are already added, you just need to add the frob_peer names for the doors/handles and the door_handle name to the door.

=== Adding a working model door handle===

Quick summary:
* Create a model or brush handle and make it an ''atdm:mover_door_handle'' entity.
* Position it on your door. Use the opposite side from the door's multicolor X-Y-Z indicator (highlight the door to see it) if it's not obvious which side it goes on.
* '''Bind''' the handle to the door (bind <doorname>)
* It should now be a working handle though may need adjustments of rotation etc. see later.

Important: read preceding section on door handle types and performance issues first.

This works with both a model door and a brush door:

'''Rotation''':
* By default the door handle entity rotates ''anti-clockwise'' (looked at from the front) then springs back. A ''double handle'' model is OK but two singles (see ''Multiple door handles'' below) need more care as only one is the functioning entity and the other is just attached to it. So anti-clockwise is fine for a door with its hinge on the left and the handle on the right - the handle will rotate down then spring back. If you put the functioning door handle on the other side you will have to change the default ''rotate'' property from -45 0 0 to 45 0 0. '''''Therefore it is easier to generally put this handle on the side of the door where the hinge is on the left and the non-functioning attachment handle on the other side.'''''
*If your door only needs one handle, eg, a cupboard door, and from outside its hinge is on the right then you will need to change the ''rotate'' property of the handle as described above.

'''''The functioning handle entity:'''''
* Create an entity door handle (movers folder) or create a brush or model handle and assign it the entity ''atdm:mover_door_handle''.
* Position it where you wish on your door.
* '''Bind''' the handle to the door, by adding the "bind" spawnarg to the handle.

You now have a working door handle with default properties.

*'''Multiple door handles''':
Now that you've got a handle attached to one side of the door it is time to add one to the other side (unless you used a double handle).
* Create the new handle. The single handles come in left and right persuasions. A door needs a left facing handle on one side and a right facing handle on the other, so if you have already added the left handle create a right handle and line it up on the other side of the door.
* Name this handle. I prefer to keep a naming convention for each door and it's respective handles, it makes things alot easier. The door is named '''My_Door_1''', the first handle is named '''My_Handle_1''' so name the second handle '''My_Handle_1_1'''. This will make it stay with the first handle in the entity list. This is important to keep organized. If you name it My_Handle_2 then when you get to another door named My_Door_2 you'll be confused.
* Place and '''bind''' that handle to your door.

You now have two single door handles on either side of the door that rotate together as if they were physically attached.

'''To add a brush to a brush door''':
* Select the new brush ''and'' the brush door all together; ''the entity '''must''' be selected '''last'''.''
* Use {{menu|Edit|Reparent primitives}}. This ensures the parent entity adopts the new item(s).
* If you have trouble selecting them in the orthoview because other brushes, etc. get selected then try in the camera view or as a last resort move them temporarily to an open area (but keep them in the same positions relative to each other.) Use {{key-shift}}+{{LMB}} on new item(s) then {{key-shift}}+{{LMB}} on main entity. Once they are all selected, use the {{menu|Edit|Reparent primitives}}.

'''To add ''model'' static items''': knockers, hinges, static handles etc. to a ''Model Door'':
* Select item
* Right click in orthoview and select ''Create Entity'' then <code>entity func_static</code>
* Position it where you wish on your door.
* To synchronize this with your particular door you need to add the property ''bind'' and the individual door name to the brush entity. To do this...
** Select the model door.
** In the entity inspector, select the ''name'' line
** Select the bottom line in the input box ''below'' the properties window.
** Copy the name
** Deselect the door with {{key-esc}}
** Select the brush entity
** Add a property "bind" to it.
** Change the value of the property by pasting in the door name
** Click {{check}} or press {{key-enter}}

'''To add ''brush'' static items''': knockers, hinges, static handles to a Model Door:
* This method is not ideal but it seems to work OK.
* Select the brush.
* Right click in orthoview and select Create Entity then ''atdm:mover_door_handle''
* Position it where you wish on your door.

To synchronize this with your particular door you need to add the property ''door_handle'' on the door, and give as the value the name of the brush you just created.

This brush turns like a handle. To stop it:

* Adding ''rotate 0 0 0'' or disabling the handle script won't help.
* Add a real working handle (as in the section above ''To add a working model door handle...'' and it must be added LAST.)

If you don't want too see a real working handle added maybe try another tiny brush with the handle function and hide it inside the door?

===Locking Doors===

To lock a door check the ''show inherited properties'' in the entity inspector for a ''atdm:mover_door'' entity and you should see the ''locked'' property. Select it and in the input box below the properties you can change its value:

* 0 = unlocked (default)
* 1 = locked

If locked it will require an entity that is associated with it to be able to act as a key to unlock it.

Currently door handles on locked doors will rotate when frobbed, they will bounce back though and the door will stay locked until unlocked.

===Keys===

Assigning specific keys to specific doors is simple.

* It is recommended that you create an existing key entity. These keys have all required props, they just need to be named.

Alternatively you can create a key from the Model Viewer and want it to be useable
* Make sure it has the properties:
useable 1 [so it can be used by the door]
frobable 1
inv_name <unique name>
inv_category Keys
inv_target player1
inv_icon guis/assets/hud/inventory_icons/<icon name>
inv_stackable 0 or 1 where 1 can be used on all copies of the same key so they show as one entry in the inventory with a total.

Add to the door the property <code>used_by</code> with the name of the key as the value. Multiple keys can open the same door by using several <tt>used_by</tt> spawnargs:

"used_by" "doorkey_1"
"used_by1" "doorkey_2

==== Keys Carried by AI ====

So you have a door and you have a guard AI and you want the guard to be able to open/close/lock the door, but you also want the player to be able to pickpocket the key. Keys can be attached to AI in two ways.

''The Def_Attach Method''. This method is the best one for doors that you expect the AI to operate. It uses spawnargs to spawn the key at game start.

*"def_attach6" "atdm:prop_silverkey" // the entity to spawn - in this case a key.
*"pos_attach6" "belt_back_right" // where the key will spawn on the Ai.
*"name_attach6" "door_key" // this gives 'attach6' arg the name "door_key" and is the name the arg "used_by" will need, eg: "used_by" "door_key"
*"set inv_name on door_key" "Door key" // The name the key get when the play adds it to their inventory.
*"set name on door_key" "door_key" // here it gets a name to be used in the map in general.

For more info on this method, see [[Attaching Props to AI]].

''The Bind Method''. This lacks the animation finesse of def_attach, but does let you see the key in DR. The method is particularly helpful in, say, adding a second key to an AI in the back middle of a belt. The AI cannot use a bound key to open a locked door; the workaround is to fake it with "can_unlock" as discussed further below. Or to use bound keys mainly for items the AI will not attempt to open, such as hatches, duct covers, or chests.

* Load a key entity
* Position where you want it in relation to the AI, and bind it to them (i.e., "bind" "<AIname>")
* Add the spawnarg "bindToJoint" "Hips" (or another location like LeftHips_Dummy; see AI for list)
* Adjust existing spawnargs accordingly (that is, be sure the name and door's/chest's "used_by" match, if you aren't using a prefab chest with key). This is for the benefit of the player after pickpocketing the key; as stated above, the AI itself can't use it for unlocking.

For more info on this method, see [[Attaching_Items]] and [[BindToJoint]].

====Keys Carried by Player====

With a door's key selected in your inventory and the door highlighted, you can...
* unlock it (which will also auto-open if enabled) by either frobbing it or hitting the Use key (typically U or Enter).
* lock (or relock) it via the Use key. Why do this? To avoid pursuit, or to lure guards into a room, and then lock them in (if they don't have a key or specific can_unlock powers).

====Master Key for Testing====

By default, ALL locks can be opened by any key named ''key_master''. Just create a key in your map, name it ''key_master'' and it becomes a master key for use while testing. Add inv_map_start 1 to it so it is in the player inventory at game start. Remember to delete it when your mission is finished.

====Automatically Removing Keys from Player Inventory After Use====

If a fan mission has a lot of keys it can clog up the player inventory. If the key is single-use, it can be useful to automatically remove it from the player inventory after use. Below is a way to do it using a simple setup and a generic script function that can be used for multiple doors.
You'll need the following entities, preferably set up near each other in your map:
* The door entity itself
* A trigger_count entity
* An atdm:target_callscriptfunction entity
* some random entity for the target_callscriptfunction to target (explanation below)

The below diagram shows the spawnargs and targeting required for the setup:
[[File:Key remove2.png|left|thumb]]

<div style="clear: both"></div>
The script being called ('openDoor') is defined in fms/<mapname>/maps/<mapname>.script and looks like this:

void openDoor(entity target, entity door, entity callscriptfunction)
{
string keyName = door.getKey("used_by");
entity key = sys.getEntity(keyName);
$player1.replaceInvItem(key, $null_entity);
}

Explanation as follows:

'''For the door:'''
* '''trigger_on_open''' spawnarg: The door is configured to trigger its targets when it opens
* target '''trigger_count''' entity: this is the entity that is triggered when the door is opened
* '''used_by''' spawnarg: This names the key entity required for unlocking the door
* The other spawnargs are just the usual for setting the door as locked and unpickable

'''trigger_count entity:'''
* When triggered, this entity will in turn trigger the script that removes the key from the player inventory.
* '''count''' spawnarg: This is set to 1 because we only want the key removal script called once - the first time the player opens the door.
* this entity targets the atdm:target_callscriptfunction, which contains details of the script to execute

'''atdm:target_callscriptfunction entity:'''
* '''call''' spawnarg: This is the name of the script function to call
* '''foreach''' spawnarg: This version of the script event provides access to the 'activator', or the entity that triggered it (in this case, the door). Using that information we can obtain the key name. See [[A to Z Scripting: Ways of calling a script#target_callscriptfunction|here]] for details.
* '''target any static entity''': For this version of the script event to work, the target_callscriptfunction entity needs to target something. This can be any static entity in the map (i.e. one that won't get removed or anything). I usually just target the nearest entity (e.g. a light or a lamp, or a model). This provides no functionality in the context of this tutorial, it just satisfies the conditions of the script event.

'''The script:'''
* Pretty self-explanatory. The script gets the name of the key entity via the '''used_by''' spawnarg on the door, retrieves the key entity, and then replaces it in the player inventory with a null entity, effectively removing it.
* Any door can use this script as its generic (although they will need their own trigger_count and target_callscriptfunction entities)

===Lockpicks===
''by Baddcog''

There are two lock pick types.
*'''s'''=snake
*'''t'''=triangular

A lock can be set with many pins. Each pin has a click sequence and each needs a designated lockpick type (see above). Keep in mind that the lockpicking in The Darkmod is much more involved than in T2 or T3. The player has to listen to sounds or watch a handle or lockbar to know when a lock is pin is picked.

This means that authors can be very evil and really frustrate the player, in which case their missions will probably not be played. So be nice to the player and don't waste your time. Use simple locks for the most part and save complicated locks for important sections and to build tension. Don't make the player have 20 pins to pick all with different lockpicks. In most cases 1 or 2 pins will suffice and it isn't necessary to use both lockpicks on every lock.
Also try to include a lock lever on lockboxes or chests, door handles will rotate as the pins are being picked. This gives the player visual clues to help with the picking (and essential in noisy environments where you can't hear the clicks.)
IMO this system is a huge leap foward for lockpicking but also has the ability to completely frustrate the player as stated above. Keep this in mind when designing your lockpick systems.

These props go on the door itself, or the lid of a chest, eg,
*'''lock_pins''' 1327
*'''lock_picktype''' stts

The lock_pins property specifies how many pins each lockpicktype has.
The lockpick_type property specifies how many times the player has to switch picks and which pick they have to use. You can see there must always be an equal number of lock_pins and lock_picktypes specified

So looking at the example above we have lockpick_type s(snake), t(triangular), t(triangular), and s(snake). The player will have to use these lockpicks in this order. Once the snake lockpick's pins are open the player can advance to the triangular pick and so forth.
5 is added to every click sequence so 5 is the minimum click pattern even if you set it to 0.
In the example above the lockpins specify in order which pick types have how many pins, so the s pick has 1 + 5 = 6 clicks, the t pick has 8 and so on.
The above is a difficult lock and to avoid annoying the player it is best only used rarely on a special lock like an important big vault door. Ordinary footlockers and common doors can be just 1 or 2 click sequences, eg, lock_pins 2 and lock_picktype t means the player uses one pick and listens for the end of one sequence of 7 clicks.

lockpick_rotate - is placed on the door. It is the amount the visible rotating handle or pin rotates while picking. For a rotating handle or lockbar normally ignore this and leave the default. During lockpicking it oscillates and progresses to the normal full turn of the handle. Example 0 45 0.

lockpick_translate - is placed on the door. It is the amount the visible handle or pin moves in a straight line while picking. Use this if you have eg, a lockbar that you want to move in a straight line and not rotate, eg sliding catch. Example 0 -5 0

By default, doors are pickable. If you don't set up the above lockpick spawnargs then it can't be picked. So there is normally no need to enable lockpicking - just set up the above spawnargs. There is a ''pickable'' spawnarg set to 1 by default. If set to 0 then the door becomes unpickable. But hard to think of an application except in testing or perhaps a special custom situation where it is switched by script perhaps.

===Open, Partially Open, or Closed Door at Game Start===

By default, doors are closed at game start. If you want a door to be already open or partially open then do the following.

'''Note well: Create all doors in their ''closed'' position. Adjust as follows and they will automatically be at the open position when game starts.'''

Already Open Rotating Door:
* Select the door.
* Select the entity inspector
* Check ''show inherited properties''
* Select the ''open'' property
* Edit the value to 1 in the input box below and tick the check button
* The door will now be fully open at game start.

* If you want it only partly open:
* Make sure its ''open'' property is set to 1 as above.
* Right click the entity inspector and select ''add property''
* Click the + sign on the left of the top line where atdm:mover_door is listed to open the folder. (if atdm:mover_door is not listed then the entity was likely changed from eg, func_static. If so, save the map and reload to update the add property list)
* scroll down, select ''start_rotate'' then click {{ok}}
* This adds it to the property list.
* Now select ''start_rotate'' in the property list.
* Edit the bottom line of the input box ''below'' the properties window to the angle you want in the same form as described in the ''Rotate Direction and Open Angle'' section. So for example, to have a door that has a fully open default ''rotate'' value of 0 90 0 to start only half open you would give it a ''start_rotate'' value of 0 45 0.
* In a similar way add the property ''first_frob_open".
* Set it to 1 and a partly open door should then open fully on the first frob.
* Set it to 0 and a partly open door should close on the first frob.

Already Open Sliding Door:
* Select the door.
* Select the entity inspector
* Check ''show inherited properties''
* Select the ''open'' property
* Edit the value to 1 in the input box below and click {{check}} or press {{key-enter}}
* The door will now be fully open at game start.

* If you want it only partly open:
* Right click the entity inspector and select ''add property''
* Make sure its ''open'' property is set to 1
* Click the + sign on the left of the top line where atdm:mover_door is listed to open the folder.
* scroll down, select ''start_position'' then click OK. (if atdm:mover_door is not listed then the entity was likely changed from eg, func_static. If so, save the map and reload to update the add property list)
* This adds it to the property list.
* Now select ''start_position'' in the property list.
* Edit the bottom line of the input box ''below'' the properties window to the position you want in the same form as described in the ''Sliding (Translation) Amount and Direction'' section. So for example, to have a door that has a fully open default ''translate'' value of 0 50 0 to start only half open you would give it a ''start_position'' value of 0 25 0.
* In a similar way add the property ''first_frob_open".
* Set it to 1 and a partly open door should then open fully on the first frob.
* Set it to 0 and a partly open door should close on the first frob.

===Rotation Centre, Pivot, Hinge point===

The centre of rotation of a door is at the origin point of its entity and the door rotates with reference to the orientation of that origin point, not the world map. See ''Rotate Direction...'' for more about that. This section only deals with the ''position'' of the rotation centre in the door.

Model Door Centre of Rotation:<br>
The centre of rotation of a model door cannot be changed within Dark Radiant. Because a model door rotates around the centre 'spine' of its back edge this will cause clipping (penetration into solid) as in this example (where the door is set to open to 89 degrees for clarity):<BR>[[Image:modelClipping.jpg]]<BR> So care is needed with placement. You will not normally position a door right next to a wall as in the example but against a shallow frame so clipping will barely be noticeable but either way it can be fixed. You can correct it by adding a translation (see ''Sliding (Translation) Directions'') value of half the door width in the direction of the door handle. This will gently move the door out as it rotates to clear any solid on that side as in this diagram:<br>
[[Image:DoorClip.jpg]]<br>
Half a door width will typically be about 2. Any 'attachments' such as door handles will still synchronize with the door movement whether the door is rotating, sliding, or both.

Brush Door Centre of Rotation:<br>
The centre of rotation of a brush door ''can'' be changed. The default origin point of a brush is at its centre. Therefore a default rotating brush door will rotate around its centre when you first create it. So, mappers will commonly need to move that rotation point to a corner or even to some other offset position for example, for an openable window using the door function.

Put simply, to move the rotation point of a brush door you need to move the entity origin relative to the brush(es.)

Moving the entity origin (centre of rotation) relative to a brush door:

* Select the brush door
* Select ''Vertices mode'' (default shortcut key is {{key|name=V}} or button on top toolbar 'Select Vertices')
* Drag the door's entity origin to the point where you want the door to rotate. This should be on the corner on the leading edge side (the side to where the door is opening.) to avoid clipping as in this diagram....
[[Image:getCorner.jpg]]
* You should now find that door rotates around that point.

===Rotate Direction and Open Angle===

By default, rotating doors open anti-clockwise (viewed from above) by 90 degrees from the start orientation. If you want to change this edit the ''rotate'' property in the entity inspector. Don't confuse this ''rotate'' property with the ''rotation'' property. In the entity inspector remember that to see the inherited rotate property you must check the box 'Show inherited properties'.

The three values shown in the rotate property are degrees from the closed position around Y Z X (absolute map axes Front, Top, Side views in DR's ortho view.)

* Positive Y = Open clockwise (Dark Radiant grid front view, looking north)
* Negative Y = Open anti-clockwise (Dark Radiant grid front view, looking north)

* Positive Z = Open anti-clockwise (Dark Radiant grid top view, looking down)
* Negative Z = Open clockwise (Dark Radiant grid top view, looking down)

* Positive X = Open anti-clockwise (Dark Radiant grid side view, looking west)
* Negative X = Open clockwise (Dark Radiant grid side view, looking west)

There is a problem when you come to rotations that are not around the main Y Z X axes of the map, for instance a drawbridge that lowers down to the south east. You might think you can combine Y Z X values to get the result you want - and this can be done (for south east use 45 45 90) but it is a bit of a kludge and the drawbridge twists eccentrically as it lowers (though it arrives correctly!)

The values are in the range -179 to +180. Positive values give an anti-clockwise opening rotation (looking down from above) and negative values give a clockwise opening rotation. The value 180 is unique in that it continues in an anti-clockwise rotation when closing rather than returning clockwise so might be used if you can think of some object that might need such a motion when frobbed!

Edit the rotate value by selecting it and using the input box at the bottom and clicking the check(tick) button. That will change the angle the door will open to. Note that the line with the original default of 0 90 0 will still be there but your new entry will be added on a separate line and that is the one that will work in the game. CAUTION: when adjusting later make sure you have your new line selected and not the original! If you do it will appear to change but your first setting will remain unaltered.

Examples:
* 0 90 0 = Opens anti-clockwise round the entity's 'vertical' to 90 degrees - typical default vertical door.
* 0 0 90 = Lowers a drawbridge from the entity 'vertical' to horizontal.
* 0 0 -45 = Opens clockwise by 45 degrees viewed from the east side. This might suit a skylight in a sloping roof.

'rotate' cannot be combined with translate motions (see [[#Sliding (Translation) Amount and Direction]]) in one door; you need to bind one door to another and link they by targetting one to the other. By that means you can produce exotic and useful motions. A door opening against an upward-sloping floor can thus have a ''lifting hinge'' and raise up slightly to clear the floor; a door can rotate towards you and slide back to one side very effectively.

===Sliding (Translation) Amount and Direction===

By default a Dark Mod door will rotate open. For most sliding doors you want to stop them rotating as well as make them slide. You cannot delete (remove) the ''rotate'' property - you have to set the ''rotate'' property to 0 0 0 to stop a door rotating (see ''Rotate Direction and Open Angle''.)

Now edit the ''translate'' property value by selecting it (remember to have inherited properties box checked) and using the input box at the bottom and clicking the check(tick) button. That will change the distance the door will slide to. Note that the line with the original default of 0 0 0 will still be there but your new entry will be added on a separate line and that is the one that will work in the game. CAUTION: when adjusting later make sure you have your new line selected and not the original! If you do it will appear to change but your first setting will remain unaltered.

Typically (but not always) you will want your sliding door to slide the width of the door. The three values in the translate property by default are 0 0 0 and are X Y Z ''absolute map'' values (irrespective of door orientation) where:

* Positive X = Slide East (Right side of Dark Radiant grid in top view)
* Negative X = Slide West (Left side of Dark Radiant grid in top view)
* Positive Y = Slide North (top of Dark Radiant grid in top view)
* Negative Y = Slide South (bottom of Dark Radiant grid in top view)
* Positive Z = Slide Up (Top of Dark Radiant grid in side views)
* Negative Z = Slide Down (Bottom of Dark Radiant grid in side views)

So for a 50 unit wide door you want to slide fully to the east you would use 50 0 0 for the translate property values. A 100 unit portcullis sliding vertically up would need 0 0 100 to be fully raised.

=== Doors Collision/Push Behaviour ===
Doors push all entities by default, except for the player. Doors will also stop moving when anything blocks their movement. However, this default behaviour can be changed by setting appropriate spawnargs:

Set '''push_player''' to '''1''' to let the player be pushed by this door:
"push_player" "1" // Push the player too (default is off)

By default '''stop_when_blocked''' is set to 1 and if a door is blocked by an entity then even if the entity is removed afterwards, the door stays where it is. The next frob will close the door.

Set '''stop_when_blocked''' to '''0''' to prevent the door from ending the opening sequence when anything blocks its way. It will still pause - but continue to open if the block is removed.
"stop_when_blocked" "0" // door keeps moving after being blocked (default is off)
With this setting, doors will still stop at blocking entities (the player, for instance), but will continue to move when the entity moves out of the way.

There is another spawnarg which stops a door pushing a moveable. Apply this to the ''moveable'', not the door...

"notPushable" "1"

===Door Sounds===

There are multiple ways to put sounds on doors.

''snd_open'' <br>
Sound is triggered as the door begins to open.

''snd_opened'' <br>
Sound is triggered when the door finishes opening. Defaults to "nosound".

''snd_move''<br>
The sound plays while the door moves. Defaults to "nosound".

''snd_close'' <br>
Sound is triggered as the door finishes closing.

The following sounds should be left on the default sound in most cases so players clearly know what is going on:

''snd_locked''<br>
The sound played when a player or an AI tries to open a locked door.

''snd_unlock string''<br>
The sound played when a door is unlocked.

You can silence any of these sounds by setting the following properties as shown:

''snd_open nosound''<br>
''snd_close nosound''

Don't just use a dash - as it seems to cause a sound of its own.

===Sound Propagation through Doors and Doorways===

''This information will change significantly with the release of 2.0. See'' [[Controlling Sound Loss Across Portals]]

The sound volume reduction to the player (ie, the sound the player hears) is fixed and constant in a cvar which adds a distance factor to the original sound. It is recommended that you do not change that because it will affect other FMs. Currently there is no way to change the way that sound to the player is reduced through doors and doorways.

Sound propagation to AI, eg, impact sounds or guard yells is treated separately:

Sound propagation to AI relies on visportals. For details study [[Sound Propagation: Part 1]] and [[Sound Propagation: Part 2]] as well as [[Visportals]] This tutorial will just cover the relevant sound and sound propagation ''properties'' of doors. If you set the ''show inherited properties'' box in the entity inspector you can see them as described here.

Remember, the following have no effect on what the player hears through a door or doorway.

''loss_open''<br>
Drop in sound volume in dB propagated to AI (not player) when going through an open door. (default 1dB)

''loss_closed''<br>
Drop in sound volume in dB propagated to AI (not player) when going through a closed door. (default 15dB) You would want to set this very high to block all sound with a thick door but very low for a barred gate for example.

''loss_double_open''<br>
Drop in sound volume in dB propagated to AI (not player) when going through double doors when only one is open. (default 1dB)

There are also various sound properties for lockpicking:<br>
''snd_lockpick_pin_1 through 14'' and ''snd_lockpick_pin_success''

===Allowing the Player to Interrupt Door Motion===

The door property ''interruptable'' determines whether a door can be stopped by frobbing while it is opening or closing. It is enabled (i.e., set to 1) by default. Then the player, by frobbing to start the normal opening, then frobbing again to interrupt, can open a door to any position, e.g., slightly ajar to peek through. Another frob will begin closing, and so on with any additional frobs to stop/reverse-direction.

Be aware that an rotating-style door, when left ajar, will subsequently open or close more slowly than normal in an angular-velocity sense. It instead takes the same time as a full (uninterrupted) opening or closing would take in seconds, as given by ''move_time'' discussed next.

===Speed of Door Opening and Closing===

Rotating Door Speed:<br>
The time a rotating door takes to open or close is set in the ''move_time'' property, no matter what its maximum open angle may be. So with rotation set at, say, 150 degrees the door just opens faster than at, say, 80 degrees. To change this value, make sure the door is selected then...

* Right click the entity inspector and check ''show inherited properties''
* Scroll down, select ''move_time''
* Edit the second line of the input box ''below'' the properties window to the time you want.
* The time is in seconds and decimal fractions can be used. The default is currently 1.75 seconds.

Sliding Door Speed:<br>
The speed of a sliding door is set in the ''translate_speed'' property. To add this, make sure the door is selected then...

* Right click the entity inspector and check ''show inherited properties''
* Scroll down, select ''translate_speed''
* Edit the second line of the input box ''below'' the properties window to the speed you want.
* The speed is in Dark Radiant grid units per second.
* The default is 0 and if set to this then the door slides open in one second whatever the distance, great or small.
* CAUTION: It is assumed ''translate'' has been changed from its default value of 0 0 0. If not, a non-zero ''translate_speed'' may cause problems.

===Visportals and Doors===

A visportal face surrounded by solid at its edges and in contact with a door is closed when the door is closed and enabled when the door is open. In most cases you will place a visportal in contact with a working door unless you can see through the door (such as a true glass door or barred gate*.) For full details see [[Visportals]].

''*As of 2.0 it is possible to make visportals that remain transparent when closed for gates and windows. See'' [[Controlling Sound Loss Across Portals]]

==Auto-Closing/Opening Doors==
Doors that automatically close after being open for some time are easy to setup: Each frobmover entity supports these spawnargs:

;"auto_close_time":Set this to something >= 0 to let the mover automatically close (again) after this time when being fully opened (measured in seconds). Defaults to -1, which means 'do not autoclose'. The event is also activated when the mover starts at the open position at map start.
;"auto_open_time":"Set this to something >= 0 to let the mover automatically open (again) after this time when being fully closed (measured in seconds). Defaults to -1, which means 'do not autoopen'. The event is also activated when the mover starts at the closed position at map start.

<div class="toccolours mw-collapsible mw-collapsed">
Before auto_close_time and the AI Door Management spawnargs next were provided, a more laborious method was used to auto-close doors as if AI were closing doors behind them. Hit "Expand" to review it.
<div class="mw-collapsible-content">I have one door that I particularly want the AI to close as there is a bit of frame lag inside if not. So I set this up and it works good as an auto-closing door - not as good as a true AI closing door as it will auto close when the player goes through as well but it does look very effective to see AI going through and closing the door behind them. Not tested exhaustively so I don't know if there could be any downside. Here's what to do....

First a quick summary to make it more clear:

'''''A trigger_relay is used both as a relay AND carries a stim. We put the trigger_relay with its stim in the path of the open door. The door has a response property. When it opens and contacts the stim its response is to send a signal back to the relay. The relay pauses then closes the door...'''''

* First, optionally give your door a suitable name like autodoor1, whatever.
* Copy that name to the clipboard.

Next we need a relay with a delay:

* Create entity > darkmod > trigger_relay

* Place it roughly at the position the door will be at when open and to be on the safe side 3/4th of the way to the far end of the door (not the hinge end) to give max distance from the close door.

* Add the property 'target' and paste in the door name you just copied.

* Give the relay itself a name, eg, autoDoor_relay_1, and copy that name to the clipboard, you'll need that too in a bit.

* Add the property delay and the value 3 - this is the delay in seconds before the door will close; 3 seems about right but 2 might be worth a try because to that 3 is added a random value between 0 to 0.5 seconds from the Time Interval we entered for the stim firings.

* Add the property 'wait' and the value 3. This is the time before it can work again in seconds. If you set it too low then in theory the door might trigger again but in this situation I don't think it's possible. Too long, eg, one minute, and it won't work if the AI goes back through the door before then. If this value is -1 then the whole thing will only work ONCE so might be used for an AI who goes through once, closes it behind him, but you don't want it to be an autodoor thereafter.

That's the relay, now we add a stim to it:

* Still with the trigger relay selected, go to {{menu|Entity|Stim/Response}}

* Custom stim tab.

* Click Add stim type, select the new custom stim type you just made at the bottom of the list and type in eg, autoDoorStim at top right in the input box.

* Click the stim tab and the little drop down arrow against the 'type' selector at bottom left and you should see your new custom stim name. Select it.

* Select the new autoDoorStim in the list and on the right you need only type in the radius box 15.0 There is quite a lot of room for error. I had it working on 10 and also on 25. The value should be less than the distance to the closed door else it will trigger open! But no so small that the door might not reach it.

* Select the check box for Time Interval and enter 500 (millisecs.) This is so it doesn't keep firing more frequently than is necessary. This stim will be firing all through your mission whether the door is used or not so if you had dozens of these then maybe it would affect performance. Too big a number and there may be a long delay before the door shuts - but it will be random depending on the next time the stim happens to fire. We'll control the delay we want more precisely later.

* Click {{ok}} to confirm it.

That's the stim set up, now for the response to it which is put on the door....

* Select the doorm, then use {{menu|Entity|Stim/response}} and select the response tab.

* Click the little drop down arrow against the 'type' selector at bottom left and you should see your new custom stim name. Select it.

* Right click in the big ''Response Effects'' box on the bottom right of the panel.

* Add New Effect and you should get a default 'Activate Response' response added to the list. Double click it.

* In the Effect selector at the stop select 'Trigger'

* in the Target box, paste in the name of the relay you copied or you can select it from the list at the little arrow.

* Leave the Activator box empty.

* Click {{apply}} and then {{ok}} on the main S & R panel bottom right.

It should now work. No need to wait for an AI, just frob the door and watch it close itself. If not, check the position of the stim brush is close to where the door stops when open.</div>
</div>

==AI Door management==

By default AI will open doors and close them behind them. Here are some spawnargs '''on the door''' the mapper can use to modify that behaviour:

;"ai_should_not_handle" :If set to 1, AI will not attempt to handle it and add it to the forbidden areas (so that it doesn't try to path through). They might still walk through the door when it is open though. Useful if you have some special use door that you don't want the AI to operate.

;"ai_should_not_close" :If set to 1, AI will not close the door behind them unless it obstructs them.

;"canRemainOpen" :If set to 1, it's the same as "ai_should_not_close, with the added behavior that this is ignored if the door needs to be relocked, or the door is marked "shouldBeClosed". '''(This spawnarg is available starting in TDM 2.02.)'''

Spawnargs '''on the AI''' that the mapper can use:

;"canCloseDoors" :Added in 2.12. Defaults to 1. If set to 0, the AI will not close doors after passing through them.

To get AI to unlock/relock specific doors there are two methods:

1. Provide the AI with the key, as detailed in the def_attach method in [[#Keys_carried_by_AI]] above.

2. Add the following spawnarg/value to the AI:

;"can_unlock" ''<doorname>''

For additional doors on the same AI use ''can_unlock1 doorname', `can_unlock2 doorname' etc. '''Do NOT use can_unlock_1.'''

If both (1) and (2) are used, then the AI can still go through the door after the player pickpockets the key. Otherwise, unless someone else opens the door for the AI, a typical sequence is that the AI checks their pockets for the missing key, stalls a bit at the locked door, and then (with now-better pathing algorithms) the AI uses an alternate route to the next path_corner, or "mentally" skips ahead in the route to next reachable node and goes there.

===Door Handling Positions===

It is also possible to set custom door handling positions for the AI. This is especially useful when the standard routine that lets the AI choose their standing positions while opening and closing the door fails, leaving them standing still, or circling around in front of the door helplessly.

Place a movers > ''atdm:door_handling_position'' entity where you want the AI to stand while opening/closing the door from this side.

On the door, you need to set the spawnarg "door_handle_position" "name_of_door_handling_position". You can also place a ''door_handling_position'' on each side of the door, and the AI will automatically choose the right one. In this case, you need to set spawnargs with "door_handle_position_1" etc., and the corresponding names of the ''door_handling_position'' entities on the door.

The ''door_handling_position'' entities can also carry spawnargs that define the behaviour of the AI, which are useful for example for doors that can only be opened or locked from one side:

'''"ai_no_open"''' If set to "1", the AI will not try to open the door from this side (but will still walk through when the door is already open).

'''"ai_no_close"''' If set to "1", the AI will not attempt to close the door from this side.

'''"ai_no_unlock"''' If set "1", the AI will not be able to unlock the door from this side, but still use it when it is not locked.

'''"ai_no_lock"''' If this is set "1", the AI will not lock the door from this side.

===Door Controllers===

'''Available in TDM 2.02+'''

You can design a door so it's operated by buttons or levers or switches (aka ''controllers'').

A controller is simply an entity that targets the door. Typical examples of entities that can be used are:

* Buttons: atdm:mover_button
* Levers: atdm:switch_rotate_lever
* Switch: atdm:mover_lever
* Lock: atdm:froblock. (See also next section)

1. Set up the door in the normal manner. It can be a rotating door, a sliding door, a locked door, etc.

2. Turn off the "frobable" spawnarg on the door. ("frobable" "0")

3. Create a controller entity on each side of the door. If you're setting up a locked door using atdm:froblock, there's no need to put any locking information on the controllers. When the game starts, it will transfer any locking information from the door to the controllers.

4. Give each controller the door as a target.

Both the player and any AI that wants to use the door will use the controllers to operate it. Any key, "can_unlock", or lockpick settings you would normally use at the door are now used at the controllers.

Controllers and ''door_handling_position'' entities can be used on the same door, but in that situation the ''door_handling_position'' entities don't define where the AI stands to operate the door. They simply provide the "ai_no_*" spawnargs that define AI behavior on each side of the door.

If you wish, you could provide a controller on only one side of the door instead of both sides. Note that, since the door is not frobable, the player won't be able to operate the door from the non-controller side.

====More about Using a Separate "Froblock" Lock Plate====
''by Geep, 2021-22''

Froblock, just discussed as a controller method, actually predated the controller concept in TDM. Here we recap that earlier context, with an alternative treatment of highlighting, and thoughts on texturing and usage.

Suppose you want to have a lock plate (typically mounted on a door frame or wall) that opens a nearby door, where the door and lock plate highlight separately. A traditional way is to adapt the ''froblock'' method described under the "Making your own" section of [[Containers, Chests, etc.]]

Basically, your door is the "chest lid" (of class atdm:mover_door) and your lock is the "chest body" (of class atdm:froblock). Set the properties as described in the wiki. There is a stock texture (darkmod/door/keyhole_metal_001) you can use to decorate a surface of your lock plate, or a patch on it. This method is probably most apt for small hatches and grates designed for the player alone, and with no handles, or non-turning handles attached with "bind".

===AI and 'non-frobable' Doors===
Be aware that the 'frobable' spawnarg only applies to the player, not AI. If you set a door to be non-frobable (i.e. 'frobable' '0'), AI can still operate it by interacting directly with it, even if it has a controller. For example they will do this if:

* they are fleeing or chasing the player
* the door has a controller but the AI can't reach it (for example the controller is on the other side of the door)

The best way to mitigate this is to use Door Handling Position entities (see above) with the 'ai_no_open' spawnarg set on them.

===AI locking doors behind them===

If one AI is involved (no one else is in the queue), he'll lock it behind him if he had to unlock it in the first place.

Prior to TDM 1.08, if more than one AI is using the door at the same time (there's a queue), the first AI unlocks the door, and the last AI through will only lock it if it's marked "should_always_be_locked" AND they have a "can_unlock" for that door or they have a key for that door. The last AI to use the door doesn't know that the first AI found it locked, because that info is kept per AI, and not per door.

Starting in TDM 1.08, if the first AI in a door queue found the door locked, that information is remembered by the door and the last AI through uses it to relock the door, as long as they have a "can_unlock" for that door or they have a key for that door.

In the rare case where a door is set up to use door-handling position entities (necessary for AI to use sliding doors), either or both of those entities can have the "ai_no_lock" spawnarg, which means AI aren't allowed to lock the door from that side.

==Initially Blocking a Door - Partially or Fully==
''by Geep 2021''

Suppose you have a door that you want to start out either as unopenable, or able to open just a crack, then later, after something happens, be fully openable and operational. One method known to work:

* Create a moveable object that the opening door runs into and tries to push.
* Arrange that the far side of the moveable object is jammed against some immovable worldspawn.

Here's two specific examples that use a wooden plank moveable:

* In "Perilous Refuge", a plank blocks the door leading out of the player's starting location, until the player carries it away.
* At the end of "Away0" (WIP 2021), the player tries to open a door. But if preconditions aren't met, the occupant seems to let the door open only a crack and complains. Blockage is done by an unseen plank resting on the floor hitting a knob of worldspawn. Preconditions met causes a "$plank.remove()" script call.

Other methods that you might think would work but don’t:

* Block with a func_static object, or an unjammed moveable with "notpushable 1" set. In both cases, the door travels through the object.
* In advance, "grab" an unjammed moveable to make it appear "solid" to the physics engine. (This was tested by having the player manipulate it; if it had worked, a “grabber” script call might suffice.)
* Dynamically change the door’s "rotate" limit from script using "setSpawnArg"; this function would only work before you spawn the door, not afterwards.

(Others possibilities not yet tested:

* Change "rotate" using the "setKey" script function; for some spawnargs this works even after spawn.
* Create a moveable and bind it to the world entity.
* If you are mainly interested in initially blocking an AI from using a door: it's possible that the AI re-reads the spawnargs for what doors it's allowed to open. Try adding a frob Response to the key (Entity -> Stim/Response... -> Response) with an effect that sets the “can_unlock" spawnarg on that AI to "-".)

==Controlling a Door by Scripting==
''by Geep 2021''
===If Unlocked===

Simply use, for example with a door named ''door1'':

$door1.Open();
...
$door1.Close();

Alternatively, toggle it open or closed with:

$door1.frob();

If the door has "interruptable 1" (which is the default with atdm:mover_door), you can also frob() it twice to leave it ajar. Interpose and adjust a sys.wait(...) to tune it.
===If Locked===

You need to unlock it first. Changing the door's "locked" spawnarg value won't work. Instead you will use:

$door1.Unlock();

But there are complications. By default, the door has spawnarg "open_on_unlock 1". So, assuming you didn't change that, you'd think unlocking the door would open it. But this spawnarg will be ignored if the gamer has global menu option "Open Doors on Unlock" set to Off. Assuming you want to reliably have the door open, do this:

$door1.Unlock(); // MAYBE will open door too.
sys.wait(3); // If so, wait for door to fully open. Value may need adjusting based on door's speed
$door1.Open(); // Otherwise, open it now.

The wait is added, because otherwise, the opening begun by Unlock may be stopped by Open with the door only partially open. (Probably an alternative to using sys.wait here is to zero the door's "interruptable" spawnarg.)

==Doors as Triggers==

''by Ishtvan & greebo''

Doors (or any binary frob mover, buttons, levers, etc) now have the option to [[Triggers|trigger]] their target on closing or opening. (For definition purposes, a button is defined as "closed" in the state when it starts out and "open" in the state you press it down to. I know that's a little non-intuitive, but it came from deriving from doors).

New spawnargs on frob movers:
;"trigger_on_open" :If set to 1, this binary mover will trigger its targets when it starts out completely closed and is opened.
;"trigger_when_opened":If set to 1, this binary mover will trigger its targets when it is completely opened. Code defaults to 0.
;"trigger_on_close":If set to 1, this binary mover will trigger its targets when it completely closes after being open.

== Suspicious Doors ==

If you give a door the spawnarg '''"shouldBeClosed" "1"''', then AI will treat it as suspicious if they find the door open.

Doors with that spawnarg should work like this:

- an AI opening the door knows he's not to become suspicious if he opened the door

- nearby AI alerted by the open door will also not react if they can see the door, and can see the AI that opened it

- AI who come upon the open door later probably won't be able to see the AI that opened it, so they'll treat it as suspicious

- if the AI who opened the door comes upon the door later, and it's still open, and no one's touched it since he opened it, he'll see his name on the door and won't become suspicious. "Oh, crap. I forgot to close it earlier."

- If an AI comes upon an open door that should be closed, he should close it whether he becomes suspicious or not.

'''Post TDM 2.00:'''
- AI turn to look at a door they see opening. The player can crack open a suspicious door to peek out w/o grabbing the attention of a nearby AI. After 5s, the AI will notice the cracked open door. Non-suspicious doors can be cracked open indefinitely w/o nearby AI noticing.

==Slanted or Tilted Doors==
Slanted or tilted doors can be made as follows:

1) Place your door, preferrably one of the prefab doors, which have a model door and model handle and all the rotation spawnargs pre-set.

2) rotate and place the door+handle model into place you want it to be. Now, if you use the door in the game, the door will rotate around the world z-axis, and not the door model z-axis (which is rotated).

3) to get the door to rotate around the door model z-axis, you must place a model (any model will do, and it can be placed anywhere in the map). Rotate the new model into the same orientation your door model was rotated, i.e. if you door is rotated 45 degrees around the x-axis, do the same rotation on the new model.

4) bind the doors on the new model. This makes the doors start rotating along the new model origin (which is rotated the same way as the doors).

5) working slanted door.

Do note, that all the rotated objects need to be models (suspicion, not tested). You can export DR built stuff into a model using the DR ase exporter script. For custom doors, remember that the exporter places the model origin at the map origin if you do not choose the "place origin in the middle of the object" option.

Also note that the AI probably cannot use slanted doors and might get stuck (suspicion, not tested).

There is a link to a test map here:
http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/?p=395486

==Skins: A Wide Variety of Door Textures==

This is to remind you that as with many Dark Mod models, there is a wide range of extras skins (textures) available for door models. There are now several basic door entities of different sizes so choose your size first. Then enter the spawnarg: skin with any temporary value. Now select it and click the skin button at the bottom of Dark Radiant's Entity Inspector and you will find a large of range of skin textures from which to select to give you a choice of appearances for your door.

==Extra Notes==

''func_darkmod_door'' is no longer used (just in case you come across it in the Dark Mod forums or wiki.) '''<code>atdm:mover_door</code>''' is the entity to use.

{{tutorial-editing}}

Doors

2025-11-06T19:44:21Z

Frost Salamander: /* Automatically Removing Keys from Player Inventory After Use */

{{todo}}
''Written by Fidcal'' ''edit Baddcog''

==Quick Summary==

Quick way to get an unlocked door in your map:

* Insert one of the prefab doors complete with handles and select its skin property and click the button to change its skin appearance to whatever you want. Set any other properties you need.

Alternatively,

* Create a door from the entity list
* Use the "skin" spawnarg on the door to change its appearance.
* Create a handle from the entity list
* Add the ''door_handle'' property to the door and give it the name of the handle
* To the door handle add the value frob_peer and use the name of the door.
* To open clockwise, change the ''rotate'' property from <code>0 90 0</code> to <code>0 -90 0</code>

==Introduction==

This tutorial explains how to put doors into your map using Dark Radiant, as well as adjust them and their properties.

The rest of this tutorial assumes that you have a basic understanding of using DarkRadiant. If you haven't done so, please go read the [[Dark Radiant Must Know Basic Intro]] article first.

Additionally:

* Up, down, right, and left in Dark Radiant's ''top'' orthoview are regarded here as the standard map directions of North, South, East, and West where useful for clarity.
* Where the term ''brush'' is used with a door it mostly also applies to a door made up of a group of brushes and/or patches.
* Where the term ''door'' is used it often will also apply to any object you wish to rotate when frobbed, for instance an openable window, box lid, or even more exotic objects that the imaginative mapper might conceive like a signal, engine part, toy, or whatever. So long as it needs to turn or slide just a fixed amount when frobbed then return when frobbed again then the following applies.

==Door types==

All tangible objects in Dark Mod are ''entities'', having either a pre-made model shape or else brush/patch(es). So there are two ways to create a door in Dark Radiant: as a model door or a textured brush door (or a hybrid of the two).

Models are ready made door objects but cannot within Dark Radiant (at the time of writing) be resized, rescaled, cropped or clipped whereas brushes are very flexible in that respect and can be worked into custom shapes for your map, including secret doors that blend into walls and other surfaces.

Most of the current door models are found in two places along with the door handles.
*Model Viewer: doors created from here will be static in the world and have no props other than material type.
You can add any props to them to make them working doors. If nothing else it is a good place to view the different size and skin options for the doors.
*Entity List: most of the door models can be found here. These doors have properties already assigned so they are ready to be used. Only one base door of each type is listed, create the size/hinge count door you want (2 hinge doors have a 'no hinge' skin). You can choose a skin for the door once it has been created in the editor with the "skin" spawnarg (use the model name of the door you want, taken from the model list, as its value). This is the easiest way to create a door. The same goes for door handles.

Remember also that door functions may be applied to objects other than doors, such as openable windows, drawbridges, gates, etc. In fact, anything that needs a partial rotation or slide when frobbed then return when frobbed again, such as a signal device. Lockboxes and chests use similar properties.

You can create one door/handle set and copy/paste it, but you need to take great care that all the name props are changed to match in each clone. Otherwise you get handles that fly off when a distant door moves, and handles that don't move.

==Creating a Door==

Put simply, to make a door you will be creating an 'entity with model' or 'entity with brush' or some variation thereof.

===Creating a Model Door===

There are several approaches to making a model door; the simplest is to create a door from the entity list; or create a door from the model viewer (good for static unusable prop doors).

'''Entity List''':

*Deselect everything in editor by hitting the Esc button
*Right-click an ortho view and select Create Entity
*Navigate to darkmod/movers/''atdm:door_...'', choose the door you want
*Click Add
*To change its appearance, add a "skin" spawnarg to the door, with the value being the model name of the door you want.

You now have a workable door in your level.

'''Model Viewer''':

* Right click in the orthoview, select ''Create Model'' then <code>darkmod</code> and select a door.
* Note that you can left drag the image in the ''Choose Model'' dialog to rotate it around.
* Click [[Image:Button ok.png]] and you have a static door.
* If you want to make it work (openable, frobbable) then:
** Select the entity inspector,
** Select the top classname line so it highlights
** Select the func_static line in the input box ''below'' the properties window.
** Edit <code>func_static</code> to <code>atdm:mover_door</code>
** Click {{check}} or press {{key-enter}}

Alternatively you can do it the old way:

* Create any temporary brush
* Right click in orthoview and select <code>Create Entity</code> then <code>atdm:mover_door</code>.
* Left lick the model name line in the entity inspector.
* Below it on the ''Entity Inspector'' panel you should now see a button 'Choose Model'
* Left click it, select a door model from the darkmod group.
* Note that you can left drag the image in the ''Choose Model'' dialog to rotate it around.
* The temporary brush was deleted.

In all three instances, you now have a working door with default properties.

Name your door by adding the prop (or modifing it) to name ''My_Door_1''. You can use any name that you feel is appropriate but all doors with handles attached ''must'' have their own specific name. Use the name My_Door_1 for your first attempt as it will be referenced when you get around to attaching handles (see below).

To add a handle and other adjustments, see [[#Customising and Adjusting Door Properties]] below.

===Creating a Textured Brush Door===

'''Tip:''' If unsure of size then you might insert a temporary human AI first to get a sense of height.

==== The simplest brush door: ====

* Drag out a new brush to the size required, eg, a seven foot high door is 84" x 1.1 = about 90 units in Dark Radiant.
* Give it a door texture from the texture browser (or wall texture for a secret door)
* Right click in orthoview and select ''Create Entity'' then <code>atdm:mover_door</code>

You now have a working door but it will rotate around its center. To move the rotation point to where you want the door hinges to be:
* Select the door and press 'v' or the ''Select Vertices'' button to enter vertex editing mode. The door's origin will show up as a small green square in the middle of the brush.
* In top-down orthoview, move the origin from the center to the corner of the brush. This is easiest in drag mode ('q' or the ''Resize'' button), although you can use translate mode ('w' or the ''Translate'' button) by manually selecting the vertex first.

==== Multi-brush doors: ====

More complex multi-brush doors can be created using the [[Clipper]] tool, CSG, etc. - this is not covered in this tutorial. Then assign <code>atdm:mover_door</code> for that whole brush structure. Also you can collect various brushes positioned together in relation to one another as needed, select them all, then assign <code>atdm:mover_door</code> for the group. All the brushes will be children of the <code>atdm:mover_door</code> entity and will rotate and be frobbable, etc. as one unit, as one door. To add further brushes or even model shapes later see the section on [[#Adding handles and other items to doors]].

Name your door by adding the prop (or modifing it) to name My_Door_1. You can use any name that you feel is appropriate but all doors with handles attached must have their own specific name. Use the name My_Door_1 for your first attempt as it will be referenced when you get around to attaching handles (see below). (repeated from above in case you didn't choose to create a model door)

=== Double Doors ===
Double doors are automatically recognised by the code when the doors are spawned. The prerequisite is that both doors are sharing/touching the same visportal. The spawnarg ''auto_setup_double_door'' (which defaults to "1") will take care of setting up the open/lock peer relationship between the two doors. The doors will open/close and lock/unlock along with each other as a result.

What happens behind the scenes: the doors are adding each other to their internal open_peer and lock_peer list, which causes the double doors to perform the same action when frobbed or used.

Note that ''auto_setup_double_door'' will not set the frob_peer relationship, i.e. each door will frob-highlight on its own without highlighting the other door. You'll need to add that spawnarg manually if you want to highlight the entire double door as one.

==Customising and Adjusting Door Properties==

Handles, lockplates, etc. can be added to doors and door properties can be adjusted for rotation, sliding, locking, and more.

Some of the door models have hinge plates and lockboxes that are reskinnable with a good variety of skins.

===Door handles and other door attachments===

'''Summary: just add the property ''bind'' with the door's name to the attachment and position it where you want it on the door. If it's a ''atdm:mover_door_handle'' then it automatically will work as a handle but you can bind virtually anything.'''
You can add handles and other items to doors such that they move correctly with the door whether rotating, sliding, or both and even if the door is not vertical such as a skylight or trapdoor.
Handle models come in two types, ''single handles'' and ''double handles''. A single handle is one sided, this means the handle will be inside the door or outside the door, but not both. A double handle has a lever on the inside of the door and a handle on the outside of the door. Each has benefits.

*'''''Single door handles''''':
Single door handles can be used on a static door, a door that's just for show that no AI's or the player can use. In this case you should just create a door handle from the model viewer, it will be static and have no properties such as scripts. It is for looks only. Note that TDM is trying to establish the expectation that decorative doors that cannot be opened do not have handles (though not all maps follow this).

I will call this ''multiple handles'', see more below.

These can also be useful on brush doors created in the editor that may be very thin or very wide.

*'''''Double door handles''''':
These are models have have a handle inside and outside. The bonus is that they only use one entity. Maps are limited to about 4,000 entities but when you count lights, AI, sound speakers, ect... you can run out of entities quickly on a large map. If you plan on building a large map this is the way to go, even in a small map they have benefits, namely that you only have to attach one handle per door.

Whether you decide to use a single handle or a double handle you must first follow the instructions below and attach one handle first. If you choose a double handle, follow the instructions below and you are done. If you choose a single handle type follow the instructions then also follow the ''multiple handle'' instructions for the second handle.

Both single and double handle types can be found in two places. The model viewer which will create a static model good for show, you can manually add props to make them work OR you can look in the entity browser.
Using a handle from the entity browser saves you a little bit of time as some props are already added, you just need to add the frob_peer names for the doors/handles and the door_handle name to the door.

=== Adding a working model door handle===

Quick summary:
* Create a model or brush handle and make it an ''atdm:mover_door_handle'' entity.
* Position it on your door. Use the opposite side from the door's multicolor X-Y-Z indicator (highlight the door to see it) if it's not obvious which side it goes on.
* '''Bind''' the handle to the door (bind <doorname>)
* It should now be a working handle though may need adjustments of rotation etc. see later.

Important: read preceding section on door handle types and performance issues first.

This works with both a model door and a brush door:

'''Rotation''':
* By default the door handle entity rotates ''anti-clockwise'' (looked at from the front) then springs back. A ''double handle'' model is OK but two singles (see ''Multiple door handles'' below) need more care as only one is the functioning entity and the other is just attached to it. So anti-clockwise is fine for a door with its hinge on the left and the handle on the right - the handle will rotate down then spring back. If you put the functioning door handle on the other side you will have to change the default ''rotate'' property from -45 0 0 to 45 0 0. '''''Therefore it is easier to generally put this handle on the side of the door where the hinge is on the left and the non-functioning attachment handle on the other side.'''''
*If your door only needs one handle, eg, a cupboard door, and from outside its hinge is on the right then you will need to change the ''rotate'' property of the handle as described above.

'''''The functioning handle entity:'''''
* Create an entity door handle (movers folder) or create a brush or model handle and assign it the entity ''atdm:mover_door_handle''.
* Position it where you wish on your door.
* '''Bind''' the handle to the door, by adding the "bind" spawnarg to the handle.

You now have a working door handle with default properties.

*'''Multiple door handles''':
Now that you've got a handle attached to one side of the door it is time to add one to the other side (unless you used a double handle).
* Create the new handle. The single handles come in left and right persuasions. A door needs a left facing handle on one side and a right facing handle on the other, so if you have already added the left handle create a right handle and line it up on the other side of the door.
* Name this handle. I prefer to keep a naming convention for each door and it's respective handles, it makes things alot easier. The door is named '''My_Door_1''', the first handle is named '''My_Handle_1''' so name the second handle '''My_Handle_1_1'''. This will make it stay with the first handle in the entity list. This is important to keep organized. If you name it My_Handle_2 then when you get to another door named My_Door_2 you'll be confused.
* Place and '''bind''' that handle to your door.

You now have two single door handles on either side of the door that rotate together as if they were physically attached.

'''To add a brush to a brush door''':
* Select the new brush ''and'' the brush door all together; ''the entity '''must''' be selected '''last'''.''
* Use {{menu|Edit|Reparent primitives}}. This ensures the parent entity adopts the new item(s).
* If you have trouble selecting them in the orthoview because other brushes, etc. get selected then try in the camera view or as a last resort move them temporarily to an open area (but keep them in the same positions relative to each other.) Use {{key-shift}}+{{LMB}} on new item(s) then {{key-shift}}+{{LMB}} on main entity. Once they are all selected, use the {{menu|Edit|Reparent primitives}}.

'''To add ''model'' static items''': knockers, hinges, static handles etc. to a ''Model Door'':
* Select item
* Right click in orthoview and select ''Create Entity'' then <code>entity func_static</code>
* Position it where you wish on your door.
* To synchronize this with your particular door you need to add the property ''bind'' and the individual door name to the brush entity. To do this...
** Select the model door.
** In the entity inspector, select the ''name'' line
** Select the bottom line in the input box ''below'' the properties window.
** Copy the name
** Deselect the door with {{key-esc}}
** Select the brush entity
** Add a property "bind" to it.
** Change the value of the property by pasting in the door name
** Click {{check}} or press {{key-enter}}

'''To add ''brush'' static items''': knockers, hinges, static handles to a Model Door:
* This method is not ideal but it seems to work OK.
* Select the brush.
* Right click in orthoview and select Create Entity then ''atdm:mover_door_handle''
* Position it where you wish on your door.

To synchronize this with your particular door you need to add the property ''door_handle'' on the door, and give as the value the name of the brush you just created.

This brush turns like a handle. To stop it:

* Adding ''rotate 0 0 0'' or disabling the handle script won't help.
* Add a real working handle (as in the section above ''To add a working model door handle...'' and it must be added LAST.)

If you don't want too see a real working handle added maybe try another tiny brush with the handle function and hide it inside the door?

===Locking Doors===

To lock a door check the ''show inherited properties'' in the entity inspector for a ''atdm:mover_door'' entity and you should see the ''locked'' property. Select it and in the input box below the properties you can change its value:

* 0 = unlocked (default)
* 1 = locked

If locked it will require an entity that is associated with it to be able to act as a key to unlock it.

Currently door handles on locked doors will rotate when frobbed, they will bounce back though and the door will stay locked until unlocked.

===Keys===

Assigning specific keys to specific doors is simple.

* It is recommended that you create an existing key entity. These keys have all required props, they just need to be named.

Alternatively you can create a key from the Model Viewer and want it to be useable
* Make sure it has the properties:
useable 1 [so it can be used by the door]
frobable 1
inv_name <unique name>
inv_category Keys
inv_target player1
inv_icon guis/assets/hud/inventory_icons/<icon name>
inv_stackable 0 or 1 where 1 can be used on all copies of the same key so they show as one entry in the inventory with a total.

Add to the door the property <code>used_by</code> with the name of the key as the value. Multiple keys can open the same door by using several <tt>used_by</tt> spawnargs:

"used_by" "doorkey_1"
"used_by1" "doorkey_2

==== Keys Carried by AI ====

So you have a door and you have a guard AI and you want the guard to be able to open/close/lock the door, but you also want the player to be able to pickpocket the key. Keys can be attached to AI in two ways.

''The Def_Attach Method''. This method is the best one for doors that you expect the AI to operate. It uses spawnargs to spawn the key at game start.

*"def_attach6" "atdm:prop_silverkey" // the entity to spawn - in this case a key.
*"pos_attach6" "belt_back_right" // where the key will spawn on the Ai.
*"name_attach6" "door_key" // this gives 'attach6' arg the name "door_key" and is the name the arg "used_by" will need, eg: "used_by" "door_key"
*"set inv_name on door_key" "Door key" // The name the key get when the play adds it to their inventory.
*"set name on door_key" "door_key" // here it gets a name to be used in the map in general.

For more info on this method, see [[Attaching Props to AI]].

''The Bind Method''. This lacks the animation finesse of def_attach, but does let you see the key in DR. The method is particularly helpful in, say, adding a second key to an AI in the back middle of a belt. The AI cannot use a bound key to open a locked door; the workaround is to fake it with "can_unlock" as discussed further below. Or to use bound keys mainly for items the AI will not attempt to open, such as hatches, duct covers, or chests.

* Load a key entity
* Position where you want it in relation to the AI, and bind it to them (i.e., "bind" "<AIname>")
* Add the spawnarg "bindToJoint" "Hips" (or another location like LeftHips_Dummy; see AI for list)
* Adjust existing spawnargs accordingly (that is, be sure the name and door's/chest's "used_by" match, if you aren't using a prefab chest with key). This is for the benefit of the player after pickpocketing the key; as stated above, the AI itself can't use it for unlocking.

For more info on this method, see [[Attaching_Items]] and [[BindToJoint]].

====Keys Carried by Player====

With a door's key selected in your inventory and the door highlighted, you can...
* unlock it (which will also auto-open if enabled) by either frobbing it or hitting the Use key (typically U or Enter).
* lock (or relock) it via the Use key. Why do this? To avoid pursuit, or to lure guards into a room, and then lock them in (if they don't have a key or specific can_unlock powers).

====Master Key for Testing====

By default, ALL locks can be opened by any key named ''key_master''. Just create a key in your map, name it ''key_master'' and it becomes a master key for use while testing. Add inv_map_start 1 to it so it is in the player inventory at game start. Remember to delete it when your mission is finished.

====Automatically Removing Keys from Player Inventory After Use====

If a fan mission has a lot of keys it can clog up the player inventory. If the key is single-use, it can be useful to automatically remove it from the player inventory after use. Below is a way to do it using a simple setup and a generic script function that can be used for multiple doors.
You'll need the following entities, preferably set up near each other in your map:
* The door entity itself
* A trigger_count entity
* An atdm:target_callscriptfunction entity
* some random entity for the target_callscriptfunction to target (explanation below)

The below diagram shows the spawnargs and targeting required for the setup:
[[File:Key remove2.png|left|thumb]]

<div style="clear: both"></div>
The script being called ('openDoor') is defined in fms/<mapname>/maps/<mapname>.script and looks like this:

void openDoor(entity target, entity door, entity callscriptfunction)
{
string keyName = door.getKey("used_by");
entity key = sys.getEntity(keyName);
$player1.replaceInvItem(key, $null_entity);
}

Explanation as follows:

'''For the door:'''
* '''trigger_on_open''' spawnarg: The door is configured to trigger its targets when it opens
* target '''trigger_count''' entity: this is the entity that is triggered when the door is opened
* '''used_by''' spawnarg: This names the key entity required for unlocking the door
* The other spawnargs are just the usual for setting the door as locked and unpickable

'''trigger_count entity:'''
* When triggered, this entity will in turn trigger the script that removes the key from the player inventory.
* '''count''' spawnarg: This is set to 1 because we only want the key removal script called once - the first time the player opens the door.
* this entity targets the atdm:target_callscriptfunction, which contains details of the script to execute

'''atdm:target_callscriptfunction entity:'''
* '''call''' spawnarg: This is the name of the script function to call
* '''foreach''' spawnarg: This version of the script event provides access to 'activator', or the entity that triggered it (in this case, the door). Using that information we can obtain the key name. See [[A to Z Scripting: Ways of calling a script#target_callscriptfunction|here]] for details.
* '''target any static entity''': For this version of the script event to work, the target_callscriptfunction entity needs to target something. This can be any static entity in the map (i.e. one that won't get removed or anything). I usually just target the nearest entity (e.g. a light or a lamp, or a model). This provides no functionality in the context of this tutorial, it just satisfies the conditions of the script event.

'''The script:'''
* Pretty self-explanatory. The script gets the name of the key entity via the '''used_by''' spawnarg on the door, retrieves the key entity, and then replaces it in the player inventory with a null entity, effectively removing it.
* Any door can use this script as its generic (although they will need their own trigger_count and target_callscriptfunction entities)

===Lockpicks===
''by Baddcog''

There are two lock pick types.
*'''s'''=snake
*'''t'''=triangular

A lock can be set with many pins. Each pin has a click sequence and each needs a designated lockpick type (see above). Keep in mind that the lockpicking in The Darkmod is much more involved than in T2 or T3. The player has to listen to sounds or watch a handle or lockbar to know when a lock is pin is picked.

This means that authors can be very evil and really frustrate the player, in which case their missions will probably not be played. So be nice to the player and don't waste your time. Use simple locks for the most part and save complicated locks for important sections and to build tension. Don't make the player have 20 pins to pick all with different lockpicks. In most cases 1 or 2 pins will suffice and it isn't necessary to use both lockpicks on every lock.
Also try to include a lock lever on lockboxes or chests, door handles will rotate as the pins are being picked. This gives the player visual clues to help with the picking (and essential in noisy environments where you can't hear the clicks.)
IMO this system is a huge leap foward for lockpicking but also has the ability to completely frustrate the player as stated above. Keep this in mind when designing your lockpick systems.

These props go on the door itself, or the lid of a chest, eg,
*'''lock_pins''' 1327
*'''lock_picktype''' stts

The lock_pins property specifies how many pins each lockpicktype has.
The lockpick_type property specifies how many times the player has to switch picks and which pick they have to use. You can see there must always be an equal number of lock_pins and lock_picktypes specified

So looking at the example above we have lockpick_type s(snake), t(triangular), t(triangular), and s(snake). The player will have to use these lockpicks in this order. Once the snake lockpick's pins are open the player can advance to the triangular pick and so forth.
5 is added to every click sequence so 5 is the minimum click pattern even if you set it to 0.
In the example above the lockpins specify in order which pick types have how many pins, so the s pick has 1 + 5 = 6 clicks, the t pick has 8 and so on.
The above is a difficult lock and to avoid annoying the player it is best only used rarely on a special lock like an important big vault door. Ordinary footlockers and common doors can be just 1 or 2 click sequences, eg, lock_pins 2 and lock_picktype t means the player uses one pick and listens for the end of one sequence of 7 clicks.

lockpick_rotate - is placed on the door. It is the amount the visible rotating handle or pin rotates while picking. For a rotating handle or lockbar normally ignore this and leave the default. During lockpicking it oscillates and progresses to the normal full turn of the handle. Example 0 45 0.

lockpick_translate - is placed on the door. It is the amount the visible handle or pin moves in a straight line while picking. Use this if you have eg, a lockbar that you want to move in a straight line and not rotate, eg sliding catch. Example 0 -5 0

By default, doors are pickable. If you don't set up the above lockpick spawnargs then it can't be picked. So there is normally no need to enable lockpicking - just set up the above spawnargs. There is a ''pickable'' spawnarg set to 1 by default. If set to 0 then the door becomes unpickable. But hard to think of an application except in testing or perhaps a special custom situation where it is switched by script perhaps.

===Open, Partially Open, or Closed Door at Game Start===

By default, doors are closed at game start. If you want a door to be already open or partially open then do the following.

'''Note well: Create all doors in their ''closed'' position. Adjust as follows and they will automatically be at the open position when game starts.'''

Already Open Rotating Door:
* Select the door.
* Select the entity inspector
* Check ''show inherited properties''
* Select the ''open'' property
* Edit the value to 1 in the input box below and tick the check button
* The door will now be fully open at game start.

* If you want it only partly open:
* Make sure its ''open'' property is set to 1 as above.
* Right click the entity inspector and select ''add property''
* Click the + sign on the left of the top line where atdm:mover_door is listed to open the folder. (if atdm:mover_door is not listed then the entity was likely changed from eg, func_static. If so, save the map and reload to update the add property list)
* scroll down, select ''start_rotate'' then click {{ok}}
* This adds it to the property list.
* Now select ''start_rotate'' in the property list.
* Edit the bottom line of the input box ''below'' the properties window to the angle you want in the same form as described in the ''Rotate Direction and Open Angle'' section. So for example, to have a door that has a fully open default ''rotate'' value of 0 90 0 to start only half open you would give it a ''start_rotate'' value of 0 45 0.
* In a similar way add the property ''first_frob_open".
* Set it to 1 and a partly open door should then open fully on the first frob.
* Set it to 0 and a partly open door should close on the first frob.

Already Open Sliding Door:
* Select the door.
* Select the entity inspector
* Check ''show inherited properties''
* Select the ''open'' property
* Edit the value to 1 in the input box below and click {{check}} or press {{key-enter}}
* The door will now be fully open at game start.

* If you want it only partly open:
* Right click the entity inspector and select ''add property''
* Make sure its ''open'' property is set to 1
* Click the + sign on the left of the top line where atdm:mover_door is listed to open the folder.
* scroll down, select ''start_position'' then click OK. (if atdm:mover_door is not listed then the entity was likely changed from eg, func_static. If so, save the map and reload to update the add property list)
* This adds it to the property list.
* Now select ''start_position'' in the property list.
* Edit the bottom line of the input box ''below'' the properties window to the position you want in the same form as described in the ''Sliding (Translation) Amount and Direction'' section. So for example, to have a door that has a fully open default ''translate'' value of 0 50 0 to start only half open you would give it a ''start_position'' value of 0 25 0.
* In a similar way add the property ''first_frob_open".
* Set it to 1 and a partly open door should then open fully on the first frob.
* Set it to 0 and a partly open door should close on the first frob.

===Rotation Centre, Pivot, Hinge point===

The centre of rotation of a door is at the origin point of its entity and the door rotates with reference to the orientation of that origin point, not the world map. See ''Rotate Direction...'' for more about that. This section only deals with the ''position'' of the rotation centre in the door.

Model Door Centre of Rotation:<br>
The centre of rotation of a model door cannot be changed within Dark Radiant. Because a model door rotates around the centre 'spine' of its back edge this will cause clipping (penetration into solid) as in this example (where the door is set to open to 89 degrees for clarity):<BR>[[Image:modelClipping.jpg]]<BR> So care is needed with placement. You will not normally position a door right next to a wall as in the example but against a shallow frame so clipping will barely be noticeable but either way it can be fixed. You can correct it by adding a translation (see ''Sliding (Translation) Directions'') value of half the door width in the direction of the door handle. This will gently move the door out as it rotates to clear any solid on that side as in this diagram:<br>
[[Image:DoorClip.jpg]]<br>
Half a door width will typically be about 2. Any 'attachments' such as door handles will still synchronize with the door movement whether the door is rotating, sliding, or both.

Brush Door Centre of Rotation:<br>
The centre of rotation of a brush door ''can'' be changed. The default origin point of a brush is at its centre. Therefore a default rotating brush door will rotate around its centre when you first create it. So, mappers will commonly need to move that rotation point to a corner or even to some other offset position for example, for an openable window using the door function.

Put simply, to move the rotation point of a brush door you need to move the entity origin relative to the brush(es.)

Moving the entity origin (centre of rotation) relative to a brush door:

* Select the brush door
* Select ''Vertices mode'' (default shortcut key is {{key|name=V}} or button on top toolbar 'Select Vertices')
* Drag the door's entity origin to the point where you want the door to rotate. This should be on the corner on the leading edge side (the side to where the door is opening.) to avoid clipping as in this diagram....
[[Image:getCorner.jpg]]
* You should now find that door rotates around that point.

===Rotate Direction and Open Angle===

By default, rotating doors open anti-clockwise (viewed from above) by 90 degrees from the start orientation. If you want to change this edit the ''rotate'' property in the entity inspector. Don't confuse this ''rotate'' property with the ''rotation'' property. In the entity inspector remember that to see the inherited rotate property you must check the box 'Show inherited properties'.

The three values shown in the rotate property are degrees from the closed position around Y Z X (absolute map axes Front, Top, Side views in DR's ortho view.)

* Positive Y = Open clockwise (Dark Radiant grid front view, looking north)
* Negative Y = Open anti-clockwise (Dark Radiant grid front view, looking north)

* Positive Z = Open anti-clockwise (Dark Radiant grid top view, looking down)
* Negative Z = Open clockwise (Dark Radiant grid top view, looking down)

* Positive X = Open anti-clockwise (Dark Radiant grid side view, looking west)
* Negative X = Open clockwise (Dark Radiant grid side view, looking west)

There is a problem when you come to rotations that are not around the main Y Z X axes of the map, for instance a drawbridge that lowers down to the south east. You might think you can combine Y Z X values to get the result you want - and this can be done (for south east use 45 45 90) but it is a bit of a kludge and the drawbridge twists eccentrically as it lowers (though it arrives correctly!)

The values are in the range -179 to +180. Positive values give an anti-clockwise opening rotation (looking down from above) and negative values give a clockwise opening rotation. The value 180 is unique in that it continues in an anti-clockwise rotation when closing rather than returning clockwise so might be used if you can think of some object that might need such a motion when frobbed!

Edit the rotate value by selecting it and using the input box at the bottom and clicking the check(tick) button. That will change the angle the door will open to. Note that the line with the original default of 0 90 0 will still be there but your new entry will be added on a separate line and that is the one that will work in the game. CAUTION: when adjusting later make sure you have your new line selected and not the original! If you do it will appear to change but your first setting will remain unaltered.

Examples:
* 0 90 0 = Opens anti-clockwise round the entity's 'vertical' to 90 degrees - typical default vertical door.
* 0 0 90 = Lowers a drawbridge from the entity 'vertical' to horizontal.
* 0 0 -45 = Opens clockwise by 45 degrees viewed from the east side. This might suit a skylight in a sloping roof.

'rotate' cannot be combined with translate motions (see [[#Sliding (Translation) Amount and Direction]]) in one door; you need to bind one door to another and link they by targetting one to the other. By that means you can produce exotic and useful motions. A door opening against an upward-sloping floor can thus have a ''lifting hinge'' and raise up slightly to clear the floor; a door can rotate towards you and slide back to one side very effectively.

===Sliding (Translation) Amount and Direction===

By default a Dark Mod door will rotate open. For most sliding doors you want to stop them rotating as well as make them slide. You cannot delete (remove) the ''rotate'' property - you have to set the ''rotate'' property to 0 0 0 to stop a door rotating (see ''Rotate Direction and Open Angle''.)

Now edit the ''translate'' property value by selecting it (remember to have inherited properties box checked) and using the input box at the bottom and clicking the check(tick) button. That will change the distance the door will slide to. Note that the line with the original default of 0 0 0 will still be there but your new entry will be added on a separate line and that is the one that will work in the game. CAUTION: when adjusting later make sure you have your new line selected and not the original! If you do it will appear to change but your first setting will remain unaltered.

Typically (but not always) you will want your sliding door to slide the width of the door. The three values in the translate property by default are 0 0 0 and are X Y Z ''absolute map'' values (irrespective of door orientation) where:

* Positive X = Slide East (Right side of Dark Radiant grid in top view)
* Negative X = Slide West (Left side of Dark Radiant grid in top view)
* Positive Y = Slide North (top of Dark Radiant grid in top view)
* Negative Y = Slide South (bottom of Dark Radiant grid in top view)
* Positive Z = Slide Up (Top of Dark Radiant grid in side views)
* Negative Z = Slide Down (Bottom of Dark Radiant grid in side views)

So for a 50 unit wide door you want to slide fully to the east you would use 50 0 0 for the translate property values. A 100 unit portcullis sliding vertically up would need 0 0 100 to be fully raised.

=== Doors Collision/Push Behaviour ===
Doors push all entities by default, except for the player. Doors will also stop moving when anything blocks their movement. However, this default behaviour can be changed by setting appropriate spawnargs:

Set '''push_player''' to '''1''' to let the player be pushed by this door:
"push_player" "1" // Push the player too (default is off)

By default '''stop_when_blocked''' is set to 1 and if a door is blocked by an entity then even if the entity is removed afterwards, the door stays where it is. The next frob will close the door.

Set '''stop_when_blocked''' to '''0''' to prevent the door from ending the opening sequence when anything blocks its way. It will still pause - but continue to open if the block is removed.
"stop_when_blocked" "0" // door keeps moving after being blocked (default is off)
With this setting, doors will still stop at blocking entities (the player, for instance), but will continue to move when the entity moves out of the way.

There is another spawnarg which stops a door pushing a moveable. Apply this to the ''moveable'', not the door...

"notPushable" "1"

===Door Sounds===

There are multiple ways to put sounds on doors.

''snd_open'' <br>
Sound is triggered as the door begins to open.

''snd_opened'' <br>
Sound is triggered when the door finishes opening. Defaults to "nosound".

''snd_move''<br>
The sound plays while the door moves. Defaults to "nosound".

''snd_close'' <br>
Sound is triggered as the door finishes closing.

The following sounds should be left on the default sound in most cases so players clearly know what is going on:

''snd_locked''<br>
The sound played when a player or an AI tries to open a locked door.

''snd_unlock string''<br>
The sound played when a door is unlocked.

You can silence any of these sounds by setting the following properties as shown:

''snd_open nosound''<br>
''snd_close nosound''

Don't just use a dash - as it seems to cause a sound of its own.

===Sound Propagation through Doors and Doorways===

''This information will change significantly with the release of 2.0. See'' [[Controlling Sound Loss Across Portals]]

The sound volume reduction to the player (ie, the sound the player hears) is fixed and constant in a cvar which adds a distance factor to the original sound. It is recommended that you do not change that because it will affect other FMs. Currently there is no way to change the way that sound to the player is reduced through doors and doorways.

Sound propagation to AI, eg, impact sounds or guard yells is treated separately:

Sound propagation to AI relies on visportals. For details study [[Sound Propagation: Part 1]] and [[Sound Propagation: Part 2]] as well as [[Visportals]] This tutorial will just cover the relevant sound and sound propagation ''properties'' of doors. If you set the ''show inherited properties'' box in the entity inspector you can see them as described here.

Remember, the following have no effect on what the player hears through a door or doorway.

''loss_open''<br>
Drop in sound volume in dB propagated to AI (not player) when going through an open door. (default 1dB)

''loss_closed''<br>
Drop in sound volume in dB propagated to AI (not player) when going through a closed door. (default 15dB) You would want to set this very high to block all sound with a thick door but very low for a barred gate for example.

''loss_double_open''<br>
Drop in sound volume in dB propagated to AI (not player) when going through double doors when only one is open. (default 1dB)

There are also various sound properties for lockpicking:<br>
''snd_lockpick_pin_1 through 14'' and ''snd_lockpick_pin_success''

===Allowing the Player to Interrupt Door Motion===

The door property ''interruptable'' determines whether a door can be stopped by frobbing while it is opening or closing. It is enabled (i.e., set to 1) by default. Then the player, by frobbing to start the normal opening, then frobbing again to interrupt, can open a door to any position, e.g., slightly ajar to peek through. Another frob will begin closing, and so on with any additional frobs to stop/reverse-direction.

Be aware that an rotating-style door, when left ajar, will subsequently open or close more slowly than normal in an angular-velocity sense. It instead takes the same time as a full (uninterrupted) opening or closing would take in seconds, as given by ''move_time'' discussed next.

===Speed of Door Opening and Closing===

Rotating Door Speed:<br>
The time a rotating door takes to open or close is set in the ''move_time'' property, no matter what its maximum open angle may be. So with rotation set at, say, 150 degrees the door just opens faster than at, say, 80 degrees. To change this value, make sure the door is selected then...

* Right click the entity inspector and check ''show inherited properties''
* Scroll down, select ''move_time''
* Edit the second line of the input box ''below'' the properties window to the time you want.
* The time is in seconds and decimal fractions can be used. The default is currently 1.75 seconds.

Sliding Door Speed:<br>
The speed of a sliding door is set in the ''translate_speed'' property. To add this, make sure the door is selected then...

* Right click the entity inspector and check ''show inherited properties''
* Scroll down, select ''translate_speed''
* Edit the second line of the input box ''below'' the properties window to the speed you want.
* The speed is in Dark Radiant grid units per second.
* The default is 0 and if set to this then the door slides open in one second whatever the distance, great or small.
* CAUTION: It is assumed ''translate'' has been changed from its default value of 0 0 0. If not, a non-zero ''translate_speed'' may cause problems.

===Visportals and Doors===

A visportal face surrounded by solid at its edges and in contact with a door is closed when the door is closed and enabled when the door is open. In most cases you will place a visportal in contact with a working door unless you can see through the door (such as a true glass door or barred gate*.) For full details see [[Visportals]].

''*As of 2.0 it is possible to make visportals that remain transparent when closed for gates and windows. See'' [[Controlling Sound Loss Across Portals]]

==Auto-Closing/Opening Doors==
Doors that automatically close after being open for some time are easy to setup: Each frobmover entity supports these spawnargs:

;"auto_close_time":Set this to something >= 0 to let the mover automatically close (again) after this time when being fully opened (measured in seconds). Defaults to -1, which means 'do not autoclose'. The event is also activated when the mover starts at the open position at map start.
;"auto_open_time":"Set this to something >= 0 to let the mover automatically open (again) after this time when being fully closed (measured in seconds). Defaults to -1, which means 'do not autoopen'. The event is also activated when the mover starts at the closed position at map start.

<div class="toccolours mw-collapsible mw-collapsed">
Before auto_close_time and the AI Door Management spawnargs next were provided, a more laborious method was used to auto-close doors as if AI were closing doors behind them. Hit "Expand" to review it.
<div class="mw-collapsible-content">I have one door that I particularly want the AI to close as there is a bit of frame lag inside if not. So I set this up and it works good as an auto-closing door - not as good as a true AI closing door as it will auto close when the player goes through as well but it does look very effective to see AI going through and closing the door behind them. Not tested exhaustively so I don't know if there could be any downside. Here's what to do....

First a quick summary to make it more clear:

'''''A trigger_relay is used both as a relay AND carries a stim. We put the trigger_relay with its stim in the path of the open door. The door has a response property. When it opens and contacts the stim its response is to send a signal back to the relay. The relay pauses then closes the door...'''''

* First, optionally give your door a suitable name like autodoor1, whatever.
* Copy that name to the clipboard.

Next we need a relay with a delay:

* Create entity > darkmod > trigger_relay

* Place it roughly at the position the door will be at when open and to be on the safe side 3/4th of the way to the far end of the door (not the hinge end) to give max distance from the close door.

* Add the property 'target' and paste in the door name you just copied.

* Give the relay itself a name, eg, autoDoor_relay_1, and copy that name to the clipboard, you'll need that too in a bit.

* Add the property delay and the value 3 - this is the delay in seconds before the door will close; 3 seems about right but 2 might be worth a try because to that 3 is added a random value between 0 to 0.5 seconds from the Time Interval we entered for the stim firings.

* Add the property 'wait' and the value 3. This is the time before it can work again in seconds. If you set it too low then in theory the door might trigger again but in this situation I don't think it's possible. Too long, eg, one minute, and it won't work if the AI goes back through the door before then. If this value is -1 then the whole thing will only work ONCE so might be used for an AI who goes through once, closes it behind him, but you don't want it to be an autodoor thereafter.

That's the relay, now we add a stim to it:

* Still with the trigger relay selected, go to {{menu|Entity|Stim/Response}}

* Custom stim tab.

* Click Add stim type, select the new custom stim type you just made at the bottom of the list and type in eg, autoDoorStim at top right in the input box.

* Click the stim tab and the little drop down arrow against the 'type' selector at bottom left and you should see your new custom stim name. Select it.

* Select the new autoDoorStim in the list and on the right you need only type in the radius box 15.0 There is quite a lot of room for error. I had it working on 10 and also on 25. The value should be less than the distance to the closed door else it will trigger open! But no so small that the door might not reach it.

* Select the check box for Time Interval and enter 500 (millisecs.) This is so it doesn't keep firing more frequently than is necessary. This stim will be firing all through your mission whether the door is used or not so if you had dozens of these then maybe it would affect performance. Too big a number and there may be a long delay before the door shuts - but it will be random depending on the next time the stim happens to fire. We'll control the delay we want more precisely later.

* Click {{ok}} to confirm it.

That's the stim set up, now for the response to it which is put on the door....

* Select the doorm, then use {{menu|Entity|Stim/response}} and select the response tab.

* Click the little drop down arrow against the 'type' selector at bottom left and you should see your new custom stim name. Select it.

* Right click in the big ''Response Effects'' box on the bottom right of the panel.

* Add New Effect and you should get a default 'Activate Response' response added to the list. Double click it.

* In the Effect selector at the stop select 'Trigger'

* in the Target box, paste in the name of the relay you copied or you can select it from the list at the little arrow.

* Leave the Activator box empty.

* Click {{apply}} and then {{ok}} on the main S & R panel bottom right.

It should now work. No need to wait for an AI, just frob the door and watch it close itself. If not, check the position of the stim brush is close to where the door stops when open.</div>
</div>

==AI Door management==

By default AI will open doors and close them behind them. Here are some spawnargs '''on the door''' the mapper can use to modify that behaviour:

;"ai_should_not_handle" :If set to 1, AI will not attempt to handle it and add it to the forbidden areas (so that it doesn't try to path through). They might still walk through the door when it is open though. Useful if you have some special use door that you don't want the AI to operate.

;"ai_should_not_close" :If set to 1, AI will not close the door behind them unless it obstructs them.

;"canRemainOpen" :If set to 1, it's the same as "ai_should_not_close, with the added behavior that this is ignored if the door needs to be relocked, or the door is marked "shouldBeClosed". '''(This spawnarg is available starting in TDM 2.02.)'''

Spawnargs '''on the AI''' that the mapper can use:

;"canCloseDoors" :Added in 2.12. Defaults to 1. If set to 0, the AI will not close doors after passing through them.

To get AI to unlock/relock specific doors there are two methods:

1. Provide the AI with the key, as detailed in the def_attach method in [[#Keys_carried_by_AI]] above.

2. Add the following spawnarg/value to the AI:

;"can_unlock" ''<doorname>''

For additional doors on the same AI use ''can_unlock1 doorname', `can_unlock2 doorname' etc. '''Do NOT use can_unlock_1.'''

If both (1) and (2) are used, then the AI can still go through the door after the player pickpockets the key. Otherwise, unless someone else opens the door for the AI, a typical sequence is that the AI checks their pockets for the missing key, stalls a bit at the locked door, and then (with now-better pathing algorithms) the AI uses an alternate route to the next path_corner, or "mentally" skips ahead in the route to next reachable node and goes there.

===Door Handling Positions===

It is also possible to set custom door handling positions for the AI. This is especially useful when the standard routine that lets the AI choose their standing positions while opening and closing the door fails, leaving them standing still, or circling around in front of the door helplessly.

Place a movers > ''atdm:door_handling_position'' entity where you want the AI to stand while opening/closing the door from this side.

On the door, you need to set the spawnarg "door_handle_position" "name_of_door_handling_position". You can also place a ''door_handling_position'' on each side of the door, and the AI will automatically choose the right one. In this case, you need to set spawnargs with "door_handle_position_1" etc., and the corresponding names of the ''door_handling_position'' entities on the door.

The ''door_handling_position'' entities can also carry spawnargs that define the behaviour of the AI, which are useful for example for doors that can only be opened or locked from one side:

'''"ai_no_open"''' If set to "1", the AI will not try to open the door from this side (but will still walk through when the door is already open).

'''"ai_no_close"''' If set to "1", the AI will not attempt to close the door from this side.

'''"ai_no_unlock"''' If set "1", the AI will not be able to unlock the door from this side, but still use it when it is not locked.

'''"ai_no_lock"''' If this is set "1", the AI will not lock the door from this side.

===Door Controllers===

'''Available in TDM 2.02+'''

You can design a door so it's operated by buttons or levers or switches (aka ''controllers'').

A controller is simply an entity that targets the door. Typical examples of entities that can be used are:

* Buttons: atdm:mover_button
* Levers: atdm:switch_rotate_lever
* Switch: atdm:mover_lever
* Lock: atdm:froblock. (See also next section)

1. Set up the door in the normal manner. It can be a rotating door, a sliding door, a locked door, etc.

2. Turn off the "frobable" spawnarg on the door. ("frobable" "0")

3. Create a controller entity on each side of the door. If you're setting up a locked door using atdm:froblock, there's no need to put any locking information on the controllers. When the game starts, it will transfer any locking information from the door to the controllers.

4. Give each controller the door as a target.

Both the player and any AI that wants to use the door will use the controllers to operate it. Any key, "can_unlock", or lockpick settings you would normally use at the door are now used at the controllers.

Controllers and ''door_handling_position'' entities can be used on the same door, but in that situation the ''door_handling_position'' entities don't define where the AI stands to operate the door. They simply provide the "ai_no_*" spawnargs that define AI behavior on each side of the door.

If you wish, you could provide a controller on only one side of the door instead of both sides. Note that, since the door is not frobable, the player won't be able to operate the door from the non-controller side.

====More about Using a Separate "Froblock" Lock Plate====
''by Geep, 2021-22''

Froblock, just discussed as a controller method, actually predated the controller concept in TDM. Here we recap that earlier context, with an alternative treatment of highlighting, and thoughts on texturing and usage.

Suppose you want to have a lock plate (typically mounted on a door frame or wall) that opens a nearby door, where the door and lock plate highlight separately. A traditional way is to adapt the ''froblock'' method described under the "Making your own" section of [[Containers, Chests, etc.]]

Basically, your door is the "chest lid" (of class atdm:mover_door) and your lock is the "chest body" (of class atdm:froblock). Set the properties as described in the wiki. There is a stock texture (darkmod/door/keyhole_metal_001) you can use to decorate a surface of your lock plate, or a patch on it. This method is probably most apt for small hatches and grates designed for the player alone, and with no handles, or non-turning handles attached with "bind".

===AI and 'non-frobable' Doors===
Be aware that the 'frobable' spawnarg only applies to the player, not AI. If you set a door to be non-frobable (i.e. 'frobable' '0'), AI can still operate it by interacting directly with it, even if it has a controller. For example they will do this if:

* they are fleeing or chasing the player
* the door has a controller but the AI can't reach it (for example the controller is on the other side of the door)

The best way to mitigate this is to use Door Handling Position entities (see above) with the 'ai_no_open' spawnarg set on them.

===AI locking doors behind them===

If one AI is involved (no one else is in the queue), he'll lock it behind him if he had to unlock it in the first place.

Prior to TDM 1.08, if more than one AI is using the door at the same time (there's a queue), the first AI unlocks the door, and the last AI through will only lock it if it's marked "should_always_be_locked" AND they have a "can_unlock" for that door or they have a key for that door. The last AI to use the door doesn't know that the first AI found it locked, because that info is kept per AI, and not per door.

Starting in TDM 1.08, if the first AI in a door queue found the door locked, that information is remembered by the door and the last AI through uses it to relock the door, as long as they have a "can_unlock" for that door or they have a key for that door.

In the rare case where a door is set up to use door-handling position entities (necessary for AI to use sliding doors), either or both of those entities can have the "ai_no_lock" spawnarg, which means AI aren't allowed to lock the door from that side.

==Initially Blocking a Door - Partially or Fully==
''by Geep 2021''

Suppose you have a door that you want to start out either as unopenable, or able to open just a crack, then later, after something happens, be fully openable and operational. One method known to work:

* Create a moveable object that the opening door runs into and tries to push.
* Arrange that the far side of the moveable object is jammed against some immovable worldspawn.

Here's two specific examples that use a wooden plank moveable:

* In "Perilous Refuge", a plank blocks the door leading out of the player's starting location, until the player carries it away.
* At the end of "Away0" (WIP 2021), the player tries to open a door. But if preconditions aren't met, the occupant seems to let the door open only a crack and complains. Blockage is done by an unseen plank resting on the floor hitting a knob of worldspawn. Preconditions met causes a "$plank.remove()" script call.

Other methods that you might think would work but don’t:

* Block with a func_static object, or an unjammed moveable with "notpushable 1" set. In both cases, the door travels through the object.
* In advance, "grab" an unjammed moveable to make it appear "solid" to the physics engine. (This was tested by having the player manipulate it; if it had worked, a “grabber” script call might suffice.)
* Dynamically change the door’s "rotate" limit from script using "setSpawnArg"; this function would only work before you spawn the door, not afterwards.

(Others possibilities not yet tested:

* Change "rotate" using the "setKey" script function; for some spawnargs this works even after spawn.
* Create a moveable and bind it to the world entity.
* If you are mainly interested in initially blocking an AI from using a door: it's possible that the AI re-reads the spawnargs for what doors it's allowed to open. Try adding a frob Response to the key (Entity -> Stim/Response... -> Response) with an effect that sets the “can_unlock" spawnarg on that AI to "-".)

==Controlling a Door by Scripting==
''by Geep 2021''
===If Unlocked===

Simply use, for example with a door named ''door1'':

$door1.Open();
...
$door1.Close();

Alternatively, toggle it open or closed with:

$door1.frob();

If the door has "interruptable 1" (which is the default with atdm:mover_door), you can also frob() it twice to leave it ajar. Interpose and adjust a sys.wait(...) to tune it.
===If Locked===

You need to unlock it first. Changing the door's "locked" spawnarg value won't work. Instead you will use:

$door1.Unlock();

But there are complications. By default, the door has spawnarg "open_on_unlock 1". So, assuming you didn't change that, you'd think unlocking the door would open it. But this spawnarg will be ignored if the gamer has global menu option "Open Doors on Unlock" set to Off. Assuming you want to reliably have the door open, do this:

$door1.Unlock(); // MAYBE will open door too.
sys.wait(3); // If so, wait for door to fully open. Value may need adjusting based on door's speed
$door1.Open(); // Otherwise, open it now.

The wait is added, because otherwise, the opening begun by Unlock may be stopped by Open with the door only partially open. (Probably an alternative to using sys.wait here is to zero the door's "interruptable" spawnarg.)

==Doors as Triggers==

''by Ishtvan & greebo''

Doors (or any binary frob mover, buttons, levers, etc) now have the option to [[Triggers|trigger]] their target on closing or opening. (For definition purposes, a button is defined as "closed" in the state when it starts out and "open" in the state you press it down to. I know that's a little non-intuitive, but it came from deriving from doors).

New spawnargs on frob movers:
;"trigger_on_open" :If set to 1, this binary mover will trigger its targets when it starts out completely closed and is opened.
;"trigger_when_opened":If set to 1, this binary mover will trigger its targets when it is completely opened. Code defaults to 0.
;"trigger_on_close":If set to 1, this binary mover will trigger its targets when it completely closes after being open.

== Suspicious Doors ==

If you give a door the spawnarg '''"shouldBeClosed" "1"''', then AI will treat it as suspicious if they find the door open.

Doors with that spawnarg should work like this:

- an AI opening the door knows he's not to become suspicious if he opened the door

- nearby AI alerted by the open door will also not react if they can see the door, and can see the AI that opened it

- AI who come upon the open door later probably won't be able to see the AI that opened it, so they'll treat it as suspicious

- if the AI who opened the door comes upon the door later, and it's still open, and no one's touched it since he opened it, he'll see his name on the door and won't become suspicious. "Oh, crap. I forgot to close it earlier."

- If an AI comes upon an open door that should be closed, he should close it whether he becomes suspicious or not.

'''Post TDM 2.00:'''
- AI turn to look at a door they see opening. The player can crack open a suspicious door to peek out w/o grabbing the attention of a nearby AI. After 5s, the AI will notice the cracked open door. Non-suspicious doors can be cracked open indefinitely w/o nearby AI noticing.

==Slanted or Tilted Doors==
Slanted or tilted doors can be made as follows:

1) Place your door, preferrably one of the prefab doors, which have a model door and model handle and all the rotation spawnargs pre-set.

2) rotate and place the door+handle model into place you want it to be. Now, if you use the door in the game, the door will rotate around the world z-axis, and not the door model z-axis (which is rotated).

3) to get the door to rotate around the door model z-axis, you must place a model (any model will do, and it can be placed anywhere in the map). Rotate the new model into the same orientation your door model was rotated, i.e. if you door is rotated 45 degrees around the x-axis, do the same rotation on the new model.

4) bind the doors on the new model. This makes the doors start rotating along the new model origin (which is rotated the same way as the doors).

5) working slanted door.

Do note, that all the rotated objects need to be models (suspicion, not tested). You can export DR built stuff into a model using the DR ase exporter script. For custom doors, remember that the exporter places the model origin at the map origin if you do not choose the "place origin in the middle of the object" option.

Also note that the AI probably cannot use slanted doors and might get stuck (suspicion, not tested).

There is a link to a test map here:
http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/?p=395486

==Skins: A Wide Variety of Door Textures==

This is to remind you that as with many Dark Mod models, there is a wide range of extras skins (textures) available for door models. There are now several basic door entities of different sizes so choose your size first. Then enter the spawnarg: skin with any temporary value. Now select it and click the skin button at the bottom of Dark Radiant's Entity Inspector and you will find a large of range of skin textures from which to select to give you a choice of appearances for your door.

==Extra Notes==

''func_darkmod_door'' is no longer used (just in case you come across it in the Dark Mod forums or wiki.) '''<code>atdm:mover_door</code>''' is the entity to use.

{{tutorial-editing}}

Doors

2025-11-06T19:42:34Z

Frost Salamander: /* Keys */

{{todo}}
''Written by Fidcal'' ''edit Baddcog''

==Quick Summary==

Quick way to get an unlocked door in your map:

* Insert one of the prefab doors complete with handles and select its skin property and click the button to change its skin appearance to whatever you want. Set any other properties you need.

Alternatively,

* Create a door from the entity list
* Use the "skin" spawnarg on the door to change its appearance.
* Create a handle from the entity list
* Add the ''door_handle'' property to the door and give it the name of the handle
* To the door handle add the value frob_peer and use the name of the door.
* To open clockwise, change the ''rotate'' property from <code>0 90 0</code> to <code>0 -90 0</code>

==Introduction==

This tutorial explains how to put doors into your map using Dark Radiant, as well as adjust them and their properties.

The rest of this tutorial assumes that you have a basic understanding of using DarkRadiant. If you haven't done so, please go read the [[Dark Radiant Must Know Basic Intro]] article first.

Additionally:

* Up, down, right, and left in Dark Radiant's ''top'' orthoview are regarded here as the standard map directions of North, South, East, and West where useful for clarity.
* Where the term ''brush'' is used with a door it mostly also applies to a door made up of a group of brushes and/or patches.
* Where the term ''door'' is used it often will also apply to any object you wish to rotate when frobbed, for instance an openable window, box lid, or even more exotic objects that the imaginative mapper might conceive like a signal, engine part, toy, or whatever. So long as it needs to turn or slide just a fixed amount when frobbed then return when frobbed again then the following applies.

==Door types==

All tangible objects in Dark Mod are ''entities'', having either a pre-made model shape or else brush/patch(es). So there are two ways to create a door in Dark Radiant: as a model door or a textured brush door (or a hybrid of the two).

Models are ready made door objects but cannot within Dark Radiant (at the time of writing) be resized, rescaled, cropped or clipped whereas brushes are very flexible in that respect and can be worked into custom shapes for your map, including secret doors that blend into walls and other surfaces.

Most of the current door models are found in two places along with the door handles.
*Model Viewer: doors created from here will be static in the world and have no props other than material type.
You can add any props to them to make them working doors. If nothing else it is a good place to view the different size and skin options for the doors.
*Entity List: most of the door models can be found here. These doors have properties already assigned so they are ready to be used. Only one base door of each type is listed, create the size/hinge count door you want (2 hinge doors have a 'no hinge' skin). You can choose a skin for the door once it has been created in the editor with the "skin" spawnarg (use the model name of the door you want, taken from the model list, as its value). This is the easiest way to create a door. The same goes for door handles.

Remember also that door functions may be applied to objects other than doors, such as openable windows, drawbridges, gates, etc. In fact, anything that needs a partial rotation or slide when frobbed then return when frobbed again, such as a signal device. Lockboxes and chests use similar properties.

You can create one door/handle set and copy/paste it, but you need to take great care that all the name props are changed to match in each clone. Otherwise you get handles that fly off when a distant door moves, and handles that don't move.

==Creating a Door==

Put simply, to make a door you will be creating an 'entity with model' or 'entity with brush' or some variation thereof.

===Creating a Model Door===

There are several approaches to making a model door; the simplest is to create a door from the entity list; or create a door from the model viewer (good for static unusable prop doors).

'''Entity List''':

*Deselect everything in editor by hitting the Esc button
*Right-click an ortho view and select Create Entity
*Navigate to darkmod/movers/''atdm:door_...'', choose the door you want
*Click Add
*To change its appearance, add a "skin" spawnarg to the door, with the value being the model name of the door you want.

You now have a workable door in your level.

'''Model Viewer''':

* Right click in the orthoview, select ''Create Model'' then <code>darkmod</code> and select a door.
* Note that you can left drag the image in the ''Choose Model'' dialog to rotate it around.
* Click [[Image:Button ok.png]] and you have a static door.
* If you want to make it work (openable, frobbable) then:
** Select the entity inspector,
** Select the top classname line so it highlights
** Select the func_static line in the input box ''below'' the properties window.
** Edit <code>func_static</code> to <code>atdm:mover_door</code>
** Click {{check}} or press {{key-enter}}

Alternatively you can do it the old way:

* Create any temporary brush
* Right click in orthoview and select <code>Create Entity</code> then <code>atdm:mover_door</code>.
* Left lick the model name line in the entity inspector.
* Below it on the ''Entity Inspector'' panel you should now see a button 'Choose Model'
* Left click it, select a door model from the darkmod group.
* Note that you can left drag the image in the ''Choose Model'' dialog to rotate it around.
* The temporary brush was deleted.

In all three instances, you now have a working door with default properties.

Name your door by adding the prop (or modifing it) to name ''My_Door_1''. You can use any name that you feel is appropriate but all doors with handles attached ''must'' have their own specific name. Use the name My_Door_1 for your first attempt as it will be referenced when you get around to attaching handles (see below).

To add a handle and other adjustments, see [[#Customising and Adjusting Door Properties]] below.

===Creating a Textured Brush Door===

'''Tip:''' If unsure of size then you might insert a temporary human AI first to get a sense of height.

==== The simplest brush door: ====

* Drag out a new brush to the size required, eg, a seven foot high door is 84" x 1.1 = about 90 units in Dark Radiant.
* Give it a door texture from the texture browser (or wall texture for a secret door)
* Right click in orthoview and select ''Create Entity'' then <code>atdm:mover_door</code>

You now have a working door but it will rotate around its center. To move the rotation point to where you want the door hinges to be:
* Select the door and press 'v' or the ''Select Vertices'' button to enter vertex editing mode. The door's origin will show up as a small green square in the middle of the brush.
* In top-down orthoview, move the origin from the center to the corner of the brush. This is easiest in drag mode ('q' or the ''Resize'' button), although you can use translate mode ('w' or the ''Translate'' button) by manually selecting the vertex first.

==== Multi-brush doors: ====

More complex multi-brush doors can be created using the [[Clipper]] tool, CSG, etc. - this is not covered in this tutorial. Then assign <code>atdm:mover_door</code> for that whole brush structure. Also you can collect various brushes positioned together in relation to one another as needed, select them all, then assign <code>atdm:mover_door</code> for the group. All the brushes will be children of the <code>atdm:mover_door</code> entity and will rotate and be frobbable, etc. as one unit, as one door. To add further brushes or even model shapes later see the section on [[#Adding handles and other items to doors]].

Name your door by adding the prop (or modifing it) to name My_Door_1. You can use any name that you feel is appropriate but all doors with handles attached must have their own specific name. Use the name My_Door_1 for your first attempt as it will be referenced when you get around to attaching handles (see below). (repeated from above in case you didn't choose to create a model door)

=== Double Doors ===
Double doors are automatically recognised by the code when the doors are spawned. The prerequisite is that both doors are sharing/touching the same visportal. The spawnarg ''auto_setup_double_door'' (which defaults to "1") will take care of setting up the open/lock peer relationship between the two doors. The doors will open/close and lock/unlock along with each other as a result.

What happens behind the scenes: the doors are adding each other to their internal open_peer and lock_peer list, which causes the double doors to perform the same action when frobbed or used.

Note that ''auto_setup_double_door'' will not set the frob_peer relationship, i.e. each door will frob-highlight on its own without highlighting the other door. You'll need to add that spawnarg manually if you want to highlight the entire double door as one.

==Customising and Adjusting Door Properties==

Handles, lockplates, etc. can be added to doors and door properties can be adjusted for rotation, sliding, locking, and more.

Some of the door models have hinge plates and lockboxes that are reskinnable with a good variety of skins.

===Door handles and other door attachments===

'''Summary: just add the property ''bind'' with the door's name to the attachment and position it where you want it on the door. If it's a ''atdm:mover_door_handle'' then it automatically will work as a handle but you can bind virtually anything.'''
You can add handles and other items to doors such that they move correctly with the door whether rotating, sliding, or both and even if the door is not vertical such as a skylight or trapdoor.
Handle models come in two types, ''single handles'' and ''double handles''. A single handle is one sided, this means the handle will be inside the door or outside the door, but not both. A double handle has a lever on the inside of the door and a handle on the outside of the door. Each has benefits.

*'''''Single door handles''''':
Single door handles can be used on a static door, a door that's just for show that no AI's or the player can use. In this case you should just create a door handle from the model viewer, it will be static and have no properties such as scripts. It is for looks only. Note that TDM is trying to establish the expectation that decorative doors that cannot be opened do not have handles (though not all maps follow this).

I will call this ''multiple handles'', see more below.

These can also be useful on brush doors created in the editor that may be very thin or very wide.

*'''''Double door handles''''':
These are models have have a handle inside and outside. The bonus is that they only use one entity. Maps are limited to about 4,000 entities but when you count lights, AI, sound speakers, ect... you can run out of entities quickly on a large map. If you plan on building a large map this is the way to go, even in a small map they have benefits, namely that you only have to attach one handle per door.

Whether you decide to use a single handle or a double handle you must first follow the instructions below and attach one handle first. If you choose a double handle, follow the instructions below and you are done. If you choose a single handle type follow the instructions then also follow the ''multiple handle'' instructions for the second handle.

Both single and double handle types can be found in two places. The model viewer which will create a static model good for show, you can manually add props to make them work OR you can look in the entity browser.
Using a handle from the entity browser saves you a little bit of time as some props are already added, you just need to add the frob_peer names for the doors/handles and the door_handle name to the door.

=== Adding a working model door handle===

Quick summary:
* Create a model or brush handle and make it an ''atdm:mover_door_handle'' entity.
* Position it on your door. Use the opposite side from the door's multicolor X-Y-Z indicator (highlight the door to see it) if it's not obvious which side it goes on.
* '''Bind''' the handle to the door (bind <doorname>)
* It should now be a working handle though may need adjustments of rotation etc. see later.

Important: read preceding section on door handle types and performance issues first.

This works with both a model door and a brush door:

'''Rotation''':
* By default the door handle entity rotates ''anti-clockwise'' (looked at from the front) then springs back. A ''double handle'' model is OK but two singles (see ''Multiple door handles'' below) need more care as only one is the functioning entity and the other is just attached to it. So anti-clockwise is fine for a door with its hinge on the left and the handle on the right - the handle will rotate down then spring back. If you put the functioning door handle on the other side you will have to change the default ''rotate'' property from -45 0 0 to 45 0 0. '''''Therefore it is easier to generally put this handle on the side of the door where the hinge is on the left and the non-functioning attachment handle on the other side.'''''
*If your door only needs one handle, eg, a cupboard door, and from outside its hinge is on the right then you will need to change the ''rotate'' property of the handle as described above.

'''''The functioning handle entity:'''''
* Create an entity door handle (movers folder) or create a brush or model handle and assign it the entity ''atdm:mover_door_handle''.
* Position it where you wish on your door.
* '''Bind''' the handle to the door, by adding the "bind" spawnarg to the handle.

You now have a working door handle with default properties.

*'''Multiple door handles''':
Now that you've got a handle attached to one side of the door it is time to add one to the other side (unless you used a double handle).
* Create the new handle. The single handles come in left and right persuasions. A door needs a left facing handle on one side and a right facing handle on the other, so if you have already added the left handle create a right handle and line it up on the other side of the door.
* Name this handle. I prefer to keep a naming convention for each door and it's respective handles, it makes things alot easier. The door is named '''My_Door_1''', the first handle is named '''My_Handle_1''' so name the second handle '''My_Handle_1_1'''. This will make it stay with the first handle in the entity list. This is important to keep organized. If you name it My_Handle_2 then when you get to another door named My_Door_2 you'll be confused.
* Place and '''bind''' that handle to your door.

You now have two single door handles on either side of the door that rotate together as if they were physically attached.

'''To add a brush to a brush door''':
* Select the new brush ''and'' the brush door all together; ''the entity '''must''' be selected '''last'''.''
* Use {{menu|Edit|Reparent primitives}}. This ensures the parent entity adopts the new item(s).
* If you have trouble selecting them in the orthoview because other brushes, etc. get selected then try in the camera view or as a last resort move them temporarily to an open area (but keep them in the same positions relative to each other.) Use {{key-shift}}+{{LMB}} on new item(s) then {{key-shift}}+{{LMB}} on main entity. Once they are all selected, use the {{menu|Edit|Reparent primitives}}.

'''To add ''model'' static items''': knockers, hinges, static handles etc. to a ''Model Door'':
* Select item
* Right click in orthoview and select ''Create Entity'' then <code>entity func_static</code>
* Position it where you wish on your door.
* To synchronize this with your particular door you need to add the property ''bind'' and the individual door name to the brush entity. To do this...
** Select the model door.
** In the entity inspector, select the ''name'' line
** Select the bottom line in the input box ''below'' the properties window.
** Copy the name
** Deselect the door with {{key-esc}}
** Select the brush entity
** Add a property "bind" to it.
** Change the value of the property by pasting in the door name
** Click {{check}} or press {{key-enter}}

'''To add ''brush'' static items''': knockers, hinges, static handles to a Model Door:
* This method is not ideal but it seems to work OK.
* Select the brush.
* Right click in orthoview and select Create Entity then ''atdm:mover_door_handle''
* Position it where you wish on your door.

To synchronize this with your particular door you need to add the property ''door_handle'' on the door, and give as the value the name of the brush you just created.

This brush turns like a handle. To stop it:

* Adding ''rotate 0 0 0'' or disabling the handle script won't help.
* Add a real working handle (as in the section above ''To add a working model door handle...'' and it must be added LAST.)

If you don't want too see a real working handle added maybe try another tiny brush with the handle function and hide it inside the door?

===Locking Doors===

To lock a door check the ''show inherited properties'' in the entity inspector for a ''atdm:mover_door'' entity and you should see the ''locked'' property. Select it and in the input box below the properties you can change its value:

* 0 = unlocked (default)
* 1 = locked

If locked it will require an entity that is associated with it to be able to act as a key to unlock it.

Currently door handles on locked doors will rotate when frobbed, they will bounce back though and the door will stay locked until unlocked.

===Keys===

Assigning specific keys to specific doors is simple.

* It is recommended that you create an existing key entity. These keys have all required props, they just need to be named.

Alternatively you can create a key from the Model Viewer and want it to be useable
* Make sure it has the properties:
useable 1 [so it can be used by the door]
frobable 1
inv_name <unique name>
inv_category Keys
inv_target player1
inv_icon guis/assets/hud/inventory_icons/<icon name>
inv_stackable 0 or 1 where 1 can be used on all copies of the same key so they show as one entry in the inventory with a total.

Add to the door the property <code>used_by</code> with the name of the key as the value. Multiple keys can open the same door by using several <tt>used_by</tt> spawnargs:

"used_by" "doorkey_1"
"used_by1" "doorkey_2

==== Keys Carried by AI ====

So you have a door and you have a guard AI and you want the guard to be able to open/close/lock the door, but you also want the player to be able to pickpocket the key. Keys can be attached to AI in two ways.

''The Def_Attach Method''. This method is the best one for doors that you expect the AI to operate. It uses spawnargs to spawn the key at game start.

*"def_attach6" "atdm:prop_silverkey" // the entity to spawn - in this case a key.
*"pos_attach6" "belt_back_right" // where the key will spawn on the Ai.
*"name_attach6" "door_key" // this gives 'attach6' arg the name "door_key" and is the name the arg "used_by" will need, eg: "used_by" "door_key"
*"set inv_name on door_key" "Door key" // The name the key get when the play adds it to their inventory.
*"set name on door_key" "door_key" // here it gets a name to be used in the map in general.

For more info on this method, see [[Attaching Props to AI]].

''The Bind Method''. This lacks the animation finesse of def_attach, but does let you see the key in DR. The method is particularly helpful in, say, adding a second key to an AI in the back middle of a belt. The AI cannot use a bound key to open a locked door; the workaround is to fake it with "can_unlock" as discussed further below. Or to use bound keys mainly for items the AI will not attempt to open, such as hatches, duct covers, or chests.

* Load a key entity
* Position where you want it in relation to the AI, and bind it to them (i.e., "bind" "<AIname>")
* Add the spawnarg "bindToJoint" "Hips" (or another location like LeftHips_Dummy; see AI for list)
* Adjust existing spawnargs accordingly (that is, be sure the name and door's/chest's "used_by" match, if you aren't using a prefab chest with key). This is for the benefit of the player after pickpocketing the key; as stated above, the AI itself can't use it for unlocking.

For more info on this method, see [[Attaching_Items]] and [[BindToJoint]].

====Keys Carried by Player====

With a door's key selected in your inventory and the door highlighted, you can...
* unlock it (which will also auto-open if enabled) by either frobbing it or hitting the Use key (typically U or Enter).
* lock (or relock) it via the Use key. Why do this? To avoid pursuit, or to lure guards into a room, and then lock them in (if they don't have a key or specific can_unlock powers).

====Master Key for Testing====

By default, ALL locks can be opened by any key named ''key_master''. Just create a key in your map, name it ''key_master'' and it becomes a master key for use while testing. Add inv_map_start 1 to it so it is in the player inventory at game start. Remember to delete it when your mission is finished.

====Automatically Removing Keys from Player Inventory After Use====

If a fan mission has a lot of keys it can clog up the player inventory. If the key is single-use, it can be useful to automatically remove it from the player inventory after use. Below is a way to do it using a simple setup and a generic script function that can be used for multiple doors.
You'll need the following entities, preferably set up near each other in your map:
* The door entity itself
* A trigger_count entity
* An atdm:target_callscriptfunction entity

The below diagram shows the spawnargs and targeting required for the setup:
[[File:Key remove2.png|left|thumb]]

<div style="clear: both"></div>
The script being called ('openDoor') is defined in fms/<mapname>/maps/<mapname>.script and looks like this:

void openDoor(entity target, entity door, entity callscriptfunction)
{
string keyName = door.getKey("used_by");
entity key = sys.getEntity(keyName);
$player1.replaceInvItem(key, $null_entity);
}

Explanation as follows:

'''For the door:'''
* '''trigger_on_open''' spawnarg: The door is configured to trigger its targets when it opens
* target '''trigger_count''' entity: this is the entity that is triggered when the door is opened
* '''used_by''' spawnarg: This names the key entity required for unlocking the door
* The other spawnargs are just the usual for setting the door as locked and unpickable

'''trigger_count entity:'''
* When triggered, this entity will in turn trigger the script that removes the key from the player inventory.
* '''count''' spawnarg: This is set to 1 because we only want the key removal script called once - the first time the player opens the door.
* this entity targets the atdm:target_callscriptfunction, which contains details of the script to execute

'''atdm:target_callscriptfunction entity:'''
* '''call''' spawnarg: This is the name of the script function to call
* '''foreach''' spawnarg: This version of the script event provides access to 'activator', or the entity that triggered it (in this case, the door). Using that information we can obtain the key name. See [[A to Z Scripting: Ways of calling a script#target_callscriptfunction|here]] for details.
* '''target any static entity''': For this version of the script event to work, the target_callscriptfunction entity needs to target something. This can be any static entity in the map (i.e. one that won't get removed or anything). I usually just target the nearest entity (e.g. a light or a lamp, or a model). This provides no functionality in the context of this tutorial, it just satisfies the conditions of the script event.

'''The script:'''
* Pretty self-explanatory. The script gets the name of the key entity via the '''used_by''' spawnarg on the door, retrieves the key entity, and then replaces it in the player inventory with a null entity, effectively removing it.
* Any door can use this script as its generic (although they will need their own trigger_count and target_callscriptfunction entities)

===Lockpicks===
''by Baddcog''

There are two lock pick types.
*'''s'''=snake
*'''t'''=triangular

A lock can be set with many pins. Each pin has a click sequence and each needs a designated lockpick type (see above). Keep in mind that the lockpicking in The Darkmod is much more involved than in T2 or T3. The player has to listen to sounds or watch a handle or lockbar to know when a lock is pin is picked.

This means that authors can be very evil and really frustrate the player, in which case their missions will probably not be played. So be nice to the player and don't waste your time. Use simple locks for the most part and save complicated locks for important sections and to build tension. Don't make the player have 20 pins to pick all with different lockpicks. In most cases 1 or 2 pins will suffice and it isn't necessary to use both lockpicks on every lock.
Also try to include a lock lever on lockboxes or chests, door handles will rotate as the pins are being picked. This gives the player visual clues to help with the picking (and essential in noisy environments where you can't hear the clicks.)
IMO this system is a huge leap foward for lockpicking but also has the ability to completely frustrate the player as stated above. Keep this in mind when designing your lockpick systems.

These props go on the door itself, or the lid of a chest, eg,
*'''lock_pins''' 1327
*'''lock_picktype''' stts

The lock_pins property specifies how many pins each lockpicktype has.
The lockpick_type property specifies how many times the player has to switch picks and which pick they have to use. You can see there must always be an equal number of lock_pins and lock_picktypes specified

So looking at the example above we have lockpick_type s(snake), t(triangular), t(triangular), and s(snake). The player will have to use these lockpicks in this order. Once the snake lockpick's pins are open the player can advance to the triangular pick and so forth.
5 is added to every click sequence so 5 is the minimum click pattern even if you set it to 0.
In the example above the lockpins specify in order which pick types have how many pins, so the s pick has 1 + 5 = 6 clicks, the t pick has 8 and so on.
The above is a difficult lock and to avoid annoying the player it is best only used rarely on a special lock like an important big vault door. Ordinary footlockers and common doors can be just 1 or 2 click sequences, eg, lock_pins 2 and lock_picktype t means the player uses one pick and listens for the end of one sequence of 7 clicks.

lockpick_rotate - is placed on the door. It is the amount the visible rotating handle or pin rotates while picking. For a rotating handle or lockbar normally ignore this and leave the default. During lockpicking it oscillates and progresses to the normal full turn of the handle. Example 0 45 0.

lockpick_translate - is placed on the door. It is the amount the visible handle or pin moves in a straight line while picking. Use this if you have eg, a lockbar that you want to move in a straight line and not rotate, eg sliding catch. Example 0 -5 0

By default, doors are pickable. If you don't set up the above lockpick spawnargs then it can't be picked. So there is normally no need to enable lockpicking - just set up the above spawnargs. There is a ''pickable'' spawnarg set to 1 by default. If set to 0 then the door becomes unpickable. But hard to think of an application except in testing or perhaps a special custom situation where it is switched by script perhaps.

===Open, Partially Open, or Closed Door at Game Start===

By default, doors are closed at game start. If you want a door to be already open or partially open then do the following.

'''Note well: Create all doors in their ''closed'' position. Adjust as follows and they will automatically be at the open position when game starts.'''

Already Open Rotating Door:
* Select the door.
* Select the entity inspector
* Check ''show inherited properties''
* Select the ''open'' property
* Edit the value to 1 in the input box below and tick the check button
* The door will now be fully open at game start.

* If you want it only partly open:
* Make sure its ''open'' property is set to 1 as above.
* Right click the entity inspector and select ''add property''
* Click the + sign on the left of the top line where atdm:mover_door is listed to open the folder. (if atdm:mover_door is not listed then the entity was likely changed from eg, func_static. If so, save the map and reload to update the add property list)
* scroll down, select ''start_rotate'' then click {{ok}}
* This adds it to the property list.
* Now select ''start_rotate'' in the property list.
* Edit the bottom line of the input box ''below'' the properties window to the angle you want in the same form as described in the ''Rotate Direction and Open Angle'' section. So for example, to have a door that has a fully open default ''rotate'' value of 0 90 0 to start only half open you would give it a ''start_rotate'' value of 0 45 0.
* In a similar way add the property ''first_frob_open".
* Set it to 1 and a partly open door should then open fully on the first frob.
* Set it to 0 and a partly open door should close on the first frob.

Already Open Sliding Door:
* Select the door.
* Select the entity inspector
* Check ''show inherited properties''
* Select the ''open'' property
* Edit the value to 1 in the input box below and click {{check}} or press {{key-enter}}
* The door will now be fully open at game start.

* If you want it only partly open:
* Right click the entity inspector and select ''add property''
* Make sure its ''open'' property is set to 1
* Click the + sign on the left of the top line where atdm:mover_door is listed to open the folder.
* scroll down, select ''start_position'' then click OK. (if atdm:mover_door is not listed then the entity was likely changed from eg, func_static. If so, save the map and reload to update the add property list)
* This adds it to the property list.
* Now select ''start_position'' in the property list.
* Edit the bottom line of the input box ''below'' the properties window to the position you want in the same form as described in the ''Sliding (Translation) Amount and Direction'' section. So for example, to have a door that has a fully open default ''translate'' value of 0 50 0 to start only half open you would give it a ''start_position'' value of 0 25 0.
* In a similar way add the property ''first_frob_open".
* Set it to 1 and a partly open door should then open fully on the first frob.
* Set it to 0 and a partly open door should close on the first frob.

===Rotation Centre, Pivot, Hinge point===

The centre of rotation of a door is at the origin point of its entity and the door rotates with reference to the orientation of that origin point, not the world map. See ''Rotate Direction...'' for more about that. This section only deals with the ''position'' of the rotation centre in the door.

Model Door Centre of Rotation:<br>
The centre of rotation of a model door cannot be changed within Dark Radiant. Because a model door rotates around the centre 'spine' of its back edge this will cause clipping (penetration into solid) as in this example (where the door is set to open to 89 degrees for clarity):<BR>[[Image:modelClipping.jpg]]<BR> So care is needed with placement. You will not normally position a door right next to a wall as in the example but against a shallow frame so clipping will barely be noticeable but either way it can be fixed. You can correct it by adding a translation (see ''Sliding (Translation) Directions'') value of half the door width in the direction of the door handle. This will gently move the door out as it rotates to clear any solid on that side as in this diagram:<br>
[[Image:DoorClip.jpg]]<br>
Half a door width will typically be about 2. Any 'attachments' such as door handles will still synchronize with the door movement whether the door is rotating, sliding, or both.

Brush Door Centre of Rotation:<br>
The centre of rotation of a brush door ''can'' be changed. The default origin point of a brush is at its centre. Therefore a default rotating brush door will rotate around its centre when you first create it. So, mappers will commonly need to move that rotation point to a corner or even to some other offset position for example, for an openable window using the door function.

Put simply, to move the rotation point of a brush door you need to move the entity origin relative to the brush(es.)

Moving the entity origin (centre of rotation) relative to a brush door:

* Select the brush door
* Select ''Vertices mode'' (default shortcut key is {{key|name=V}} or button on top toolbar 'Select Vertices')
* Drag the door's entity origin to the point where you want the door to rotate. This should be on the corner on the leading edge side (the side to where the door is opening.) to avoid clipping as in this diagram....
[[Image:getCorner.jpg]]
* You should now find that door rotates around that point.

===Rotate Direction and Open Angle===

By default, rotating doors open anti-clockwise (viewed from above) by 90 degrees from the start orientation. If you want to change this edit the ''rotate'' property in the entity inspector. Don't confuse this ''rotate'' property with the ''rotation'' property. In the entity inspector remember that to see the inherited rotate property you must check the box 'Show inherited properties'.

The three values shown in the rotate property are degrees from the closed position around Y Z X (absolute map axes Front, Top, Side views in DR's ortho view.)

* Positive Y = Open clockwise (Dark Radiant grid front view, looking north)
* Negative Y = Open anti-clockwise (Dark Radiant grid front view, looking north)

* Positive Z = Open anti-clockwise (Dark Radiant grid top view, looking down)
* Negative Z = Open clockwise (Dark Radiant grid top view, looking down)

* Positive X = Open anti-clockwise (Dark Radiant grid side view, looking west)
* Negative X = Open clockwise (Dark Radiant grid side view, looking west)

There is a problem when you come to rotations that are not around the main Y Z X axes of the map, for instance a drawbridge that lowers down to the south east. You might think you can combine Y Z X values to get the result you want - and this can be done (for south east use 45 45 90) but it is a bit of a kludge and the drawbridge twists eccentrically as it lowers (though it arrives correctly!)

The values are in the range -179 to +180. Positive values give an anti-clockwise opening rotation (looking down from above) and negative values give a clockwise opening rotation. The value 180 is unique in that it continues in an anti-clockwise rotation when closing rather than returning clockwise so might be used if you can think of some object that might need such a motion when frobbed!

Edit the rotate value by selecting it and using the input box at the bottom and clicking the check(tick) button. That will change the angle the door will open to. Note that the line with the original default of 0 90 0 will still be there but your new entry will be added on a separate line and that is the one that will work in the game. CAUTION: when adjusting later make sure you have your new line selected and not the original! If you do it will appear to change but your first setting will remain unaltered.

Examples:
* 0 90 0 = Opens anti-clockwise round the entity's 'vertical' to 90 degrees - typical default vertical door.
* 0 0 90 = Lowers a drawbridge from the entity 'vertical' to horizontal.
* 0 0 -45 = Opens clockwise by 45 degrees viewed from the east side. This might suit a skylight in a sloping roof.

'rotate' cannot be combined with translate motions (see [[#Sliding (Translation) Amount and Direction]]) in one door; you need to bind one door to another and link they by targetting one to the other. By that means you can produce exotic and useful motions. A door opening against an upward-sloping floor can thus have a ''lifting hinge'' and raise up slightly to clear the floor; a door can rotate towards you and slide back to one side very effectively.

===Sliding (Translation) Amount and Direction===

By default a Dark Mod door will rotate open. For most sliding doors you want to stop them rotating as well as make them slide. You cannot delete (remove) the ''rotate'' property - you have to set the ''rotate'' property to 0 0 0 to stop a door rotating (see ''Rotate Direction and Open Angle''.)

Now edit the ''translate'' property value by selecting it (remember to have inherited properties box checked) and using the input box at the bottom and clicking the check(tick) button. That will change the distance the door will slide to. Note that the line with the original default of 0 0 0 will still be there but your new entry will be added on a separate line and that is the one that will work in the game. CAUTION: when adjusting later make sure you have your new line selected and not the original! If you do it will appear to change but your first setting will remain unaltered.

Typically (but not always) you will want your sliding door to slide the width of the door. The three values in the translate property by default are 0 0 0 and are X Y Z ''absolute map'' values (irrespective of door orientation) where:

* Positive X = Slide East (Right side of Dark Radiant grid in top view)
* Negative X = Slide West (Left side of Dark Radiant grid in top view)
* Positive Y = Slide North (top of Dark Radiant grid in top view)
* Negative Y = Slide South (bottom of Dark Radiant grid in top view)
* Positive Z = Slide Up (Top of Dark Radiant grid in side views)
* Negative Z = Slide Down (Bottom of Dark Radiant grid in side views)

So for a 50 unit wide door you want to slide fully to the east you would use 50 0 0 for the translate property values. A 100 unit portcullis sliding vertically up would need 0 0 100 to be fully raised.

=== Doors Collision/Push Behaviour ===
Doors push all entities by default, except for the player. Doors will also stop moving when anything blocks their movement. However, this default behaviour can be changed by setting appropriate spawnargs:

Set '''push_player''' to '''1''' to let the player be pushed by this door:
"push_player" "1" // Push the player too (default is off)

By default '''stop_when_blocked''' is set to 1 and if a door is blocked by an entity then even if the entity is removed afterwards, the door stays where it is. The next frob will close the door.

Set '''stop_when_blocked''' to '''0''' to prevent the door from ending the opening sequence when anything blocks its way. It will still pause - but continue to open if the block is removed.
"stop_when_blocked" "0" // door keeps moving after being blocked (default is off)
With this setting, doors will still stop at blocking entities (the player, for instance), but will continue to move when the entity moves out of the way.

There is another spawnarg which stops a door pushing a moveable. Apply this to the ''moveable'', not the door...

"notPushable" "1"

===Door Sounds===

There are multiple ways to put sounds on doors.

''snd_open'' <br>
Sound is triggered as the door begins to open.

''snd_opened'' <br>
Sound is triggered when the door finishes opening. Defaults to "nosound".

''snd_move''<br>
The sound plays while the door moves. Defaults to "nosound".

''snd_close'' <br>
Sound is triggered as the door finishes closing.

The following sounds should be left on the default sound in most cases so players clearly know what is going on:

''snd_locked''<br>
The sound played when a player or an AI tries to open a locked door.

''snd_unlock string''<br>
The sound played when a door is unlocked.

You can silence any of these sounds by setting the following properties as shown:

''snd_open nosound''<br>
''snd_close nosound''

Don't just use a dash - as it seems to cause a sound of its own.

===Sound Propagation through Doors and Doorways===

''This information will change significantly with the release of 2.0. See'' [[Controlling Sound Loss Across Portals]]

The sound volume reduction to the player (ie, the sound the player hears) is fixed and constant in a cvar which adds a distance factor to the original sound. It is recommended that you do not change that because it will affect other FMs. Currently there is no way to change the way that sound to the player is reduced through doors and doorways.

Sound propagation to AI, eg, impact sounds or guard yells is treated separately:

Sound propagation to AI relies on visportals. For details study [[Sound Propagation: Part 1]] and [[Sound Propagation: Part 2]] as well as [[Visportals]] This tutorial will just cover the relevant sound and sound propagation ''properties'' of doors. If you set the ''show inherited properties'' box in the entity inspector you can see them as described here.

Remember, the following have no effect on what the player hears through a door or doorway.

''loss_open''<br>
Drop in sound volume in dB propagated to AI (not player) when going through an open door. (default 1dB)

''loss_closed''<br>
Drop in sound volume in dB propagated to AI (not player) when going through a closed door. (default 15dB) You would want to set this very high to block all sound with a thick door but very low for a barred gate for example.

''loss_double_open''<br>
Drop in sound volume in dB propagated to AI (not player) when going through double doors when only one is open. (default 1dB)

There are also various sound properties for lockpicking:<br>
''snd_lockpick_pin_1 through 14'' and ''snd_lockpick_pin_success''

===Allowing the Player to Interrupt Door Motion===

The door property ''interruptable'' determines whether a door can be stopped by frobbing while it is opening or closing. It is enabled (i.e., set to 1) by default. Then the player, by frobbing to start the normal opening, then frobbing again to interrupt, can open a door to any position, e.g., slightly ajar to peek through. Another frob will begin closing, and so on with any additional frobs to stop/reverse-direction.

Be aware that an rotating-style door, when left ajar, will subsequently open or close more slowly than normal in an angular-velocity sense. It instead takes the same time as a full (uninterrupted) opening or closing would take in seconds, as given by ''move_time'' discussed next.

===Speed of Door Opening and Closing===

Rotating Door Speed:<br>
The time a rotating door takes to open or close is set in the ''move_time'' property, no matter what its maximum open angle may be. So with rotation set at, say, 150 degrees the door just opens faster than at, say, 80 degrees. To change this value, make sure the door is selected then...

* Right click the entity inspector and check ''show inherited properties''
* Scroll down, select ''move_time''
* Edit the second line of the input box ''below'' the properties window to the time you want.
* The time is in seconds and decimal fractions can be used. The default is currently 1.75 seconds.

Sliding Door Speed:<br>
The speed of a sliding door is set in the ''translate_speed'' property. To add this, make sure the door is selected then...

* Right click the entity inspector and check ''show inherited properties''
* Scroll down, select ''translate_speed''
* Edit the second line of the input box ''below'' the properties window to the speed you want.
* The speed is in Dark Radiant grid units per second.
* The default is 0 and if set to this then the door slides open in one second whatever the distance, great or small.
* CAUTION: It is assumed ''translate'' has been changed from its default value of 0 0 0. If not, a non-zero ''translate_speed'' may cause problems.

===Visportals and Doors===

A visportal face surrounded by solid at its edges and in contact with a door is closed when the door is closed and enabled when the door is open. In most cases you will place a visportal in contact with a working door unless you can see through the door (such as a true glass door or barred gate*.) For full details see [[Visportals]].

''*As of 2.0 it is possible to make visportals that remain transparent when closed for gates and windows. See'' [[Controlling Sound Loss Across Portals]]

==Auto-Closing/Opening Doors==
Doors that automatically close after being open for some time are easy to setup: Each frobmover entity supports these spawnargs:

;"auto_close_time":Set this to something >= 0 to let the mover automatically close (again) after this time when being fully opened (measured in seconds). Defaults to -1, which means 'do not autoclose'. The event is also activated when the mover starts at the open position at map start.
;"auto_open_time":"Set this to something >= 0 to let the mover automatically open (again) after this time when being fully closed (measured in seconds). Defaults to -1, which means 'do not autoopen'. The event is also activated when the mover starts at the closed position at map start.

<div class="toccolours mw-collapsible mw-collapsed">
Before auto_close_time and the AI Door Management spawnargs next were provided, a more laborious method was used to auto-close doors as if AI were closing doors behind them. Hit "Expand" to review it.
<div class="mw-collapsible-content">I have one door that I particularly want the AI to close as there is a bit of frame lag inside if not. So I set this up and it works good as an auto-closing door - not as good as a true AI closing door as it will auto close when the player goes through as well but it does look very effective to see AI going through and closing the door behind them. Not tested exhaustively so I don't know if there could be any downside. Here's what to do....

First a quick summary to make it more clear:

'''''A trigger_relay is used both as a relay AND carries a stim. We put the trigger_relay with its stim in the path of the open door. The door has a response property. When it opens and contacts the stim its response is to send a signal back to the relay. The relay pauses then closes the door...'''''

* First, optionally give your door a suitable name like autodoor1, whatever.
* Copy that name to the clipboard.

Next we need a relay with a delay:

* Create entity > darkmod > trigger_relay

* Place it roughly at the position the door will be at when open and to be on the safe side 3/4th of the way to the far end of the door (not the hinge end) to give max distance from the close door.

* Add the property 'target' and paste in the door name you just copied.

* Give the relay itself a name, eg, autoDoor_relay_1, and copy that name to the clipboard, you'll need that too in a bit.

* Add the property delay and the value 3 - this is the delay in seconds before the door will close; 3 seems about right but 2 might be worth a try because to that 3 is added a random value between 0 to 0.5 seconds from the Time Interval we entered for the stim firings.

* Add the property 'wait' and the value 3. This is the time before it can work again in seconds. If you set it too low then in theory the door might trigger again but in this situation I don't think it's possible. Too long, eg, one minute, and it won't work if the AI goes back through the door before then. If this value is -1 then the whole thing will only work ONCE so might be used for an AI who goes through once, closes it behind him, but you don't want it to be an autodoor thereafter.

That's the relay, now we add a stim to it:

* Still with the trigger relay selected, go to {{menu|Entity|Stim/Response}}

* Custom stim tab.

* Click Add stim type, select the new custom stim type you just made at the bottom of the list and type in eg, autoDoorStim at top right in the input box.

* Click the stim tab and the little drop down arrow against the 'type' selector at bottom left and you should see your new custom stim name. Select it.

* Select the new autoDoorStim in the list and on the right you need only type in the radius box 15.0 There is quite a lot of room for error. I had it working on 10 and also on 25. The value should be less than the distance to the closed door else it will trigger open! But no so small that the door might not reach it.

* Select the check box for Time Interval and enter 500 (millisecs.) This is so it doesn't keep firing more frequently than is necessary. This stim will be firing all through your mission whether the door is used or not so if you had dozens of these then maybe it would affect performance. Too big a number and there may be a long delay before the door shuts - but it will be random depending on the next time the stim happens to fire. We'll control the delay we want more precisely later.

* Click {{ok}} to confirm it.

That's the stim set up, now for the response to it which is put on the door....

* Select the doorm, then use {{menu|Entity|Stim/response}} and select the response tab.

* Click the little drop down arrow against the 'type' selector at bottom left and you should see your new custom stim name. Select it.

* Right click in the big ''Response Effects'' box on the bottom right of the panel.

* Add New Effect and you should get a default 'Activate Response' response added to the list. Double click it.

* In the Effect selector at the stop select 'Trigger'

* in the Target box, paste in the name of the relay you copied or you can select it from the list at the little arrow.

* Leave the Activator box empty.

* Click {{apply}} and then {{ok}} on the main S & R panel bottom right.

It should now work. No need to wait for an AI, just frob the door and watch it close itself. If not, check the position of the stim brush is close to where the door stops when open.</div>
</div>

==AI Door management==

By default AI will open doors and close them behind them. Here are some spawnargs '''on the door''' the mapper can use to modify that behaviour:

;"ai_should_not_handle" :If set to 1, AI will not attempt to handle it and add it to the forbidden areas (so that it doesn't try to path through). They might still walk through the door when it is open though. Useful if you have some special use door that you don't want the AI to operate.

;"ai_should_not_close" :If set to 1, AI will not close the door behind them unless it obstructs them.

;"canRemainOpen" :If set to 1, it's the same as "ai_should_not_close, with the added behavior that this is ignored if the door needs to be relocked, or the door is marked "shouldBeClosed". '''(This spawnarg is available starting in TDM 2.02.)'''

Spawnargs '''on the AI''' that the mapper can use:

;"canCloseDoors" :Added in 2.12. Defaults to 1. If set to 0, the AI will not close doors after passing through them.

To get AI to unlock/relock specific doors there are two methods:

1. Provide the AI with the key, as detailed in the def_attach method in [[#Keys_carried_by_AI]] above.

2. Add the following spawnarg/value to the AI:

;"can_unlock" ''<doorname>''

For additional doors on the same AI use ''can_unlock1 doorname', `can_unlock2 doorname' etc. '''Do NOT use can_unlock_1.'''

If both (1) and (2) are used, then the AI can still go through the door after the player pickpockets the key. Otherwise, unless someone else opens the door for the AI, a typical sequence is that the AI checks their pockets for the missing key, stalls a bit at the locked door, and then (with now-better pathing algorithms) the AI uses an alternate route to the next path_corner, or "mentally" skips ahead in the route to next reachable node and goes there.

===Door Handling Positions===

It is also possible to set custom door handling positions for the AI. This is especially useful when the standard routine that lets the AI choose their standing positions while opening and closing the door fails, leaving them standing still, or circling around in front of the door helplessly.

Place a movers > ''atdm:door_handling_position'' entity where you want the AI to stand while opening/closing the door from this side.

On the door, you need to set the spawnarg "door_handle_position" "name_of_door_handling_position". You can also place a ''door_handling_position'' on each side of the door, and the AI will automatically choose the right one. In this case, you need to set spawnargs with "door_handle_position_1" etc., and the corresponding names of the ''door_handling_position'' entities on the door.

The ''door_handling_position'' entities can also carry spawnargs that define the behaviour of the AI, which are useful for example for doors that can only be opened or locked from one side:

'''"ai_no_open"''' If set to "1", the AI will not try to open the door from this side (but will still walk through when the door is already open).

'''"ai_no_close"''' If set to "1", the AI will not attempt to close the door from this side.

'''"ai_no_unlock"''' If set "1", the AI will not be able to unlock the door from this side, but still use it when it is not locked.

'''"ai_no_lock"''' If this is set "1", the AI will not lock the door from this side.

===Door Controllers===

'''Available in TDM 2.02+'''

You can design a door so it's operated by buttons or levers or switches (aka ''controllers'').

A controller is simply an entity that targets the door. Typical examples of entities that can be used are:

* Buttons: atdm:mover_button
* Levers: atdm:switch_rotate_lever
* Switch: atdm:mover_lever
* Lock: atdm:froblock. (See also next section)

1. Set up the door in the normal manner. It can be a rotating door, a sliding door, a locked door, etc.

2. Turn off the "frobable" spawnarg on the door. ("frobable" "0")

3. Create a controller entity on each side of the door. If you're setting up a locked door using atdm:froblock, there's no need to put any locking information on the controllers. When the game starts, it will transfer any locking information from the door to the controllers.

4. Give each controller the door as a target.

Both the player and any AI that wants to use the door will use the controllers to operate it. Any key, "can_unlock", or lockpick settings you would normally use at the door are now used at the controllers.

Controllers and ''door_handling_position'' entities can be used on the same door, but in that situation the ''door_handling_position'' entities don't define where the AI stands to operate the door. They simply provide the "ai_no_*" spawnargs that define AI behavior on each side of the door.

If you wish, you could provide a controller on only one side of the door instead of both sides. Note that, since the door is not frobable, the player won't be able to operate the door from the non-controller side.

====More about Using a Separate "Froblock" Lock Plate====
''by Geep, 2021-22''

Froblock, just discussed as a controller method, actually predated the controller concept in TDM. Here we recap that earlier context, with an alternative treatment of highlighting, and thoughts on texturing and usage.

Suppose you want to have a lock plate (typically mounted on a door frame or wall) that opens a nearby door, where the door and lock plate highlight separately. A traditional way is to adapt the ''froblock'' method described under the "Making your own" section of [[Containers, Chests, etc.]]

Basically, your door is the "chest lid" (of class atdm:mover_door) and your lock is the "chest body" (of class atdm:froblock). Set the properties as described in the wiki. There is a stock texture (darkmod/door/keyhole_metal_001) you can use to decorate a surface of your lock plate, or a patch on it. This method is probably most apt for small hatches and grates designed for the player alone, and with no handles, or non-turning handles attached with "bind".

===AI and 'non-frobable' Doors===
Be aware that the 'frobable' spawnarg only applies to the player, not AI. If you set a door to be non-frobable (i.e. 'frobable' '0'), AI can still operate it by interacting directly with it, even if it has a controller. For example they will do this if:

* they are fleeing or chasing the player
* the door has a controller but the AI can't reach it (for example the controller is on the other side of the door)

The best way to mitigate this is to use Door Handling Position entities (see above) with the 'ai_no_open' spawnarg set on them.

===AI locking doors behind them===

If one AI is involved (no one else is in the queue), he'll lock it behind him if he had to unlock it in the first place.

Prior to TDM 1.08, if more than one AI is using the door at the same time (there's a queue), the first AI unlocks the door, and the last AI through will only lock it if it's marked "should_always_be_locked" AND they have a "can_unlock" for that door or they have a key for that door. The last AI to use the door doesn't know that the first AI found it locked, because that info is kept per AI, and not per door.

Starting in TDM 1.08, if the first AI in a door queue found the door locked, that information is remembered by the door and the last AI through uses it to relock the door, as long as they have a "can_unlock" for that door or they have a key for that door.

In the rare case where a door is set up to use door-handling position entities (necessary for AI to use sliding doors), either or both of those entities can have the "ai_no_lock" spawnarg, which means AI aren't allowed to lock the door from that side.

==Initially Blocking a Door - Partially or Fully==
''by Geep 2021''

Suppose you have a door that you want to start out either as unopenable, or able to open just a crack, then later, after something happens, be fully openable and operational. One method known to work:

* Create a moveable object that the opening door runs into and tries to push.
* Arrange that the far side of the moveable object is jammed against some immovable worldspawn.

Here's two specific examples that use a wooden plank moveable:

* In "Perilous Refuge", a plank blocks the door leading out of the player's starting location, until the player carries it away.
* At the end of "Away0" (WIP 2021), the player tries to open a door. But if preconditions aren't met, the occupant seems to let the door open only a crack and complains. Blockage is done by an unseen plank resting on the floor hitting a knob of worldspawn. Preconditions met causes a "$plank.remove()" script call.

Other methods that you might think would work but don’t:

* Block with a func_static object, or an unjammed moveable with "notpushable 1" set. In both cases, the door travels through the object.
* In advance, "grab" an unjammed moveable to make it appear "solid" to the physics engine. (This was tested by having the player manipulate it; if it had worked, a “grabber” script call might suffice.)
* Dynamically change the door’s "rotate" limit from script using "setSpawnArg"; this function would only work before you spawn the door, not afterwards.

(Others possibilities not yet tested:

* Change "rotate" using the "setKey" script function; for some spawnargs this works even after spawn.
* Create a moveable and bind it to the world entity.
* If you are mainly interested in initially blocking an AI from using a door: it's possible that the AI re-reads the spawnargs for what doors it's allowed to open. Try adding a frob Response to the key (Entity -> Stim/Response... -> Response) with an effect that sets the “can_unlock" spawnarg on that AI to "-".)

==Controlling a Door by Scripting==
''by Geep 2021''
===If Unlocked===

Simply use, for example with a door named ''door1'':

$door1.Open();
...
$door1.Close();

Alternatively, toggle it open or closed with:

$door1.frob();

If the door has "interruptable 1" (which is the default with atdm:mover_door), you can also frob() it twice to leave it ajar. Interpose and adjust a sys.wait(...) to tune it.
===If Locked===

You need to unlock it first. Changing the door's "locked" spawnarg value won't work. Instead you will use:

$door1.Unlock();

But there are complications. By default, the door has spawnarg "open_on_unlock 1". So, assuming you didn't change that, you'd think unlocking the door would open it. But this spawnarg will be ignored if the gamer has global menu option "Open Doors on Unlock" set to Off. Assuming you want to reliably have the door open, do this:

$door1.Unlock(); // MAYBE will open door too.
sys.wait(3); // If so, wait for door to fully open. Value may need adjusting based on door's speed
$door1.Open(); // Otherwise, open it now.

The wait is added, because otherwise, the opening begun by Unlock may be stopped by Open with the door only partially open. (Probably an alternative to using sys.wait here is to zero the door's "interruptable" spawnarg.)

==Doors as Triggers==

''by Ishtvan & greebo''

Doors (or any binary frob mover, buttons, levers, etc) now have the option to [[Triggers|trigger]] their target on closing or opening. (For definition purposes, a button is defined as "closed" in the state when it starts out and "open" in the state you press it down to. I know that's a little non-intuitive, but it came from deriving from doors).

New spawnargs on frob movers:
;"trigger_on_open" :If set to 1, this binary mover will trigger its targets when it starts out completely closed and is opened.
;"trigger_when_opened":If set to 1, this binary mover will trigger its targets when it is completely opened. Code defaults to 0.
;"trigger_on_close":If set to 1, this binary mover will trigger its targets when it completely closes after being open.

== Suspicious Doors ==

If you give a door the spawnarg '''"shouldBeClosed" "1"''', then AI will treat it as suspicious if they find the door open.

Doors with that spawnarg should work like this:

- an AI opening the door knows he's not to become suspicious if he opened the door

- nearby AI alerted by the open door will also not react if they can see the door, and can see the AI that opened it

- AI who come upon the open door later probably won't be able to see the AI that opened it, so they'll treat it as suspicious

- if the AI who opened the door comes upon the door later, and it's still open, and no one's touched it since he opened it, he'll see his name on the door and won't become suspicious. "Oh, crap. I forgot to close it earlier."

- If an AI comes upon an open door that should be closed, he should close it whether he becomes suspicious or not.

'''Post TDM 2.00:'''
- AI turn to look at a door they see opening. The player can crack open a suspicious door to peek out w/o grabbing the attention of a nearby AI. After 5s, the AI will notice the cracked open door. Non-suspicious doors can be cracked open indefinitely w/o nearby AI noticing.

==Slanted or Tilted Doors==
Slanted or tilted doors can be made as follows:

1) Place your door, preferrably one of the prefab doors, which have a model door and model handle and all the rotation spawnargs pre-set.

2) rotate and place the door+handle model into place you want it to be. Now, if you use the door in the game, the door will rotate around the world z-axis, and not the door model z-axis (which is rotated).

3) to get the door to rotate around the door model z-axis, you must place a model (any model will do, and it can be placed anywhere in the map). Rotate the new model into the same orientation your door model was rotated, i.e. if you door is rotated 45 degrees around the x-axis, do the same rotation on the new model.

4) bind the doors on the new model. This makes the doors start rotating along the new model origin (which is rotated the same way as the doors).

5) working slanted door.

Do note, that all the rotated objects need to be models (suspicion, not tested). You can export DR built stuff into a model using the DR ase exporter script. For custom doors, remember that the exporter places the model origin at the map origin if you do not choose the "place origin in the middle of the object" option.

Also note that the AI probably cannot use slanted doors and might get stuck (suspicion, not tested).

There is a link to a test map here:
http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/?p=395486

==Skins: A Wide Variety of Door Textures==

This is to remind you that as with many Dark Mod models, there is a wide range of extras skins (textures) available for door models. There are now several basic door entities of different sizes so choose your size first. Then enter the spawnarg: skin with any temporary value. Now select it and click the skin button at the bottom of Dark Radiant's Entity Inspector and you will find a large of range of skin textures from which to select to give you a choice of appearances for your door.

==Extra Notes==

''func_darkmod_door'' is no longer used (just in case you come across it in the Dark Mod forums or wiki.) '''<code>atdm:mover_door</code>''' is the entity to use.

{{tutorial-editing}}

File:Key remove2.png

2025-11-06T19:39:45Z

Frost Salamander:

diagram showing key removal entities

File:Key remove.png

2025-11-06T19:08:53Z

Frost Salamander:

diagram showing required entities for automatic key removal

The Lieutenant 1: In Plain Sight (FM)

2025-06-26T21:36:08Z

Frost Salamander:

A fan mission for ''The Dark Mod''.

== Information ==

*'''Author:''' [[:Category:Missions by Frost_Salamander|Frost_Salamander]]
*'''Type:''' Single Mission
*'''Releases:''' 2022-07-08 (8 July 2022) - latest
*'''Version:''' 5
*'''Size:''' 13 MB
*'''EFX Reverb:''' Yes
*'''Subtitles:''' No

== Synopsis ==

''You are an intelligence officer tasked with revealing the source of a political uprising in the city of Watchgate.''

== Series ==

This FM is part of [[Fan_Mission_Series#The_Lieutenant_series|The Lieutenant]] series.

== Theme / "Genre" / Setting ==

{|class="wikitable sortable mw-collapsible mw-collapsed" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=30% data-expandtext="Show" data-collapsetext="Hide"
|-
!bgcolor=#d0d0e0 width="5%"|Click to reveal spoiler...

|-
|City Missions
|-
|}

== Threats ==

{|class="wikitable sortable mw-collapsible mw-collapsed" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=30% data-expandtext="Show" data-collapsetext="Hide"
|-
!bgcolor=#d0d0e0 width="5%"|Click to reveal spoiler...

|-
|City Missions
|-
|-
|Horror themes
|-
|}

== Links ==

[https://www.thedarkmod.com/missiondetails/?internalName=inplainsight Official Mission List link]

You can download the mission directly while in game, by using the built-in TDM fan mission downloader.

Additional DL links:

* https://missions.thedarkmod.com/inplainsight_3b85c65964c2c3cd.pk4
* https://darkmod.taaaki.za.net/fmsv2/inplainsight_3b85c65964c2c3cd.pk4
* https://darkmod-alt02.taaaki.za.net/fms/inplainsight_3b85c65964c2c3cd.pk4
* https://tdm.frydrych.org/missions/inplainsight_3b85c65964c2c3cd.pk4
* http://mirror.mstrmnds.me/missions/inplainsight_3b85c65964c2c3cd.pk4

== Gallery ==

<gallery>
The Lieutenant 1 In Plain Sight (FM) promo 1.jpg|Promotional screenshot
The Lieutenant 1 In Plain Sight (FM) promo 2.jpg|Promotional screenshot
The Lieutenant 1 In Plain Sight (FM) promo 3.jpg|Promotional screenshot
The Lieutenant 1 In Plain Sight (FM) promo 4.jpg|Promotional screenshot
The Lieutenant 1 In Plain Sight (FM) promo 5.jpg|Promotional screenshot
The Lieutenant 1 In Plain Sight (FM) promo 6.jpg|Promotional screenshot
The Lieutenant 1 In Plain Sight (FM) promo 7.jpg|Promotional screenshot
The Lieutenant 1 In Plain Sight (FM) promo 8.jpg|Promotional screenshot
</gallery>

== Discussions ==

*[https://forums.thedarkmod.com/index.php?/topic/21549-fan-mission-in-plain-sight-by-frost_salamander-20220807 TDM forums thread]

''Beware of potential spoilers !''

== Lootlists ==

TBA

== Walkthroughs ==

''Spoilers abound !''

'''Boy Lag'''
* [https://www.youtube.com/watch?v=scgUJ1nUHUA Video playthrough - Part 1]
* [https://www.youtube.com/watch?v=LHsoI2_egMY Video playthrough - Part 2]
* [https://www.youtube.com/watch?v=S6v0xnhN2Pg Video playthrough - Part 3]
* [https://www.youtube.com/watch?v=WvDceJVdcNI Video playthrough - Part 4]
* [https://www.youtube.com/watch?v=BFZg0faxu2g Video playthrough - Part 5]

'''Steve0Greatness'''
*[https://www.youtube.com/watch?v=SbDYvP6xhKI Video playthrough]

== Trivia ==

TBA

== External sites and reviews ==

*[https://www.thiefguild.com/fanmissions/39931/the-lieutenant-1-in-plain-sight Thief Guild.com FM overview and review]

== See also ==
* [https://www.thedarkmod.com/missions/ Official FMs list]
* [[Fan Missions for The Dark Mod]] - Main article on all of the published fan missions to date, in addition to the official list on the website.
* [[Fan Mission Series]] - An overview of all currently known series or campaigns of fan missions interconnected by their stories or characters. There are already plenty in TDM, and have been since its early days as an expandable game.
* [[Upcoming Fan Missions]] - An overview of Fan Missions in development or tentatively planned. (''Do not'' edit the overview.)
* [[Mission recommendation discussions]] - An overview of past discussions on what FMs the community recommends to players looking for various challenges (difficulty, size, theme, setting, objectives, etc.).
* [[Fan Mission Contests]] - An overview of past and present contests in Fan Mission creation, by members of the TDM community.

[[Category:Official FMs|The Lieutenant 1: In Plain Sight]]
[[Category:Missions by Frost_Salamander|The Lieutenant 1: In Plain Sight]]

The Lieutenant 2: High Expectations (FM)

2025-06-26T21:35:44Z

Frost Salamander: /* Series */

A fan mission for ''The Dark Mod''.

== Information ==

*'''Author:''' [[:Category:Missions by Frost_Salamander|Frost_Salamander]]
*'''Type:''' Single Mission
*'''Releases:''' 2023-04-24 (24 April 2023) - latest
*'''Version:''' 3
*'''Size:''' 42 MB
*'''EFX Reverb:''' Yes
*'''Subtitles:''' No

== Synopsis ==

''Follow the Lieutenant on his next mission to the City of Highborough.''

== Series ==

This FM is part of [[Fan_Mission_Series#The_Lieutenant_series|The Lieutenant]] series.

== Theme / "Genre" / Setting ==

{|class="wikitable sortable mw-collapsible mw-collapsed" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=30% data-expandtext="Show" data-collapsetext="Hide"
|-
!bgcolor=#d0d0e0 width="5%"|Click to reveal spoiler...

|-
|Mansion/Estate
|-
|-
|City Missions
|-
|}

== Threats ==

{|class="wikitable sortable mw-collapsible mw-collapsed" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=30% data-expandtext="Show" data-collapsetext="Hide"
|-
!bgcolor=#d0d0e0 width="5%"|Click to reveal spoiler...

|-
|Guards
|-
|}

== Links ==

[https://www.thedarkmod.com/missiondetails/?internalName=highex Official Mission List link]

You can download the mission directly while in game, by using the built-in TDM fan mission downloader.

Additional DL links:

* https://missions.thedarkmod.com/highex_84e60f7992ca1e51.pk4
* https://darkmod.taaaki.za.net/fmsv2/highex_84e60f7992ca1e51.pk4
* https://darkmod-alt02.taaaki.za.net/fms/highex_84e60f7992ca1e51.pk4
* https://tdm.frydrych.org/missions/highex_84e60f7992ca1e51.pk4
* http://mirror.mstrmnds.me/missions/highex_84e60f7992ca1e51.pk4

== Gallery ==

<gallery>
The Lieutenant 2 High Expectations (FM) promo 01.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 02.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 03.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 04.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 05.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 06.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 07.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 08.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 09.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 10.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 11.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 12.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 13.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 14.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 15.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 16.jpg|Promotional screenshot
</gallery>

== Discussions ==

*[https://forums.thedarkmod.com/index.php?/topic/21837-fan-mission-the-lieutenant-2-high-expectations-by-frost_salamander-20230424 TDM forums thread]

''Beware of potential spoilers !''

== Lootlists ==

TBA

== Walkthroughs ==

''Spoilers abound !''

'''Boy Lag'''
* [https://www.youtube.com/watch?v=ocLPBvEIqec Video playthrough - Part 1]
* [https://www.youtube.com/watch?v=KtSm9F3aBIU Video playthrough - Part 2]
* [https://www.youtube.com/watch?v=cbx_cbvtllQ Video playthrough - Part 3]
* [https://www.youtube.com/watch?v=V1R-LarggHo Video playthrough - Part 4]
* [https://www.youtube.com/watch?v=jjXv7fbJvAQ Video playthrough - Part 5]
* [https://www.youtube.com/watch?v=1XNs2J5DkUk Video playthrough - Part 6]
* [https://www.youtube.com/watch?v=8JluJnJM2OE Video playthrough - Part 7]

'''Onegin III'''
*[https://www.youtube.com/watch?v=i4UPXURwhaI Video playthrough]
*[https://www.youtube.com/watch?v=PBRHcmZqAMk Video playthrough] (Extra)

== Trivia ==

TBA

== External sites and reviews ==

*[https://www.thiefguild.com/fanmissions/39931/the-lieutenant-1-in-plain-sight Thief Guild.com FM overview and review]

== See also ==
* [https://www.thedarkmod.com/missions/ Official FMs list]
* [[Fan Missions for The Dark Mod]] - Main article on all of the published fan missions to date, in addition to the official list on the website.
* [[Fan Mission Series]] - An overview of all currently known series or campaigns of fan missions interconnected by their stories or characters. There are already plenty in TDM, and have been since its early days as an expandable game.
* [[Upcoming Fan Missions]] - An overview of Fan Missions in development or tentatively planned. (''Do not'' edit the overview.)
* [[Mission recommendation discussions]] - An overview of past discussions on what FMs the community recommends to players looking for various challenges (difficulty, size, theme, setting, objectives, etc.).
* [[Fan Mission Contests]] - An overview of past and present contests in Fan Mission creation, by members of the TDM community.

[[Category:Official FMs|The Lieutenant 2: High Expectations]]
[[Category:Missions by Frost_Salamander|The Lieutenant 2: High Expectations]]

The Lieutenant 2: High Expectations (FM)

2025-06-26T21:34:47Z

Frost Salamander: /* Series */

A fan mission for ''The Dark Mod''.

== Information ==

*'''Author:''' [[:Category:Missions by Frost_Salamander|Frost_Salamander]]
*'''Type:''' Single Mission
*'''Releases:''' 2023-04-24 (24 April 2023) - latest
*'''Version:''' 3
*'''Size:''' 42 MB
*'''EFX Reverb:''' Yes
*'''Subtitles:''' No

== Synopsis ==

''Follow the Lieutenant on his next mission to the City of Highborough.''

== Series ==

The FM is part of [[Fan_Mission_Series#The_Lieutenant_series|The Lieutenant]] series.

== Theme / "Genre" / Setting ==

{|class="wikitable sortable mw-collapsible mw-collapsed" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=30% data-expandtext="Show" data-collapsetext="Hide"
|-
!bgcolor=#d0d0e0 width="5%"|Click to reveal spoiler...

|-
|Mansion/Estate
|-
|-
|City Missions
|-
|}

== Threats ==

{|class="wikitable sortable mw-collapsible mw-collapsed" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=30% data-expandtext="Show" data-collapsetext="Hide"
|-
!bgcolor=#d0d0e0 width="5%"|Click to reveal spoiler...

|-
|Guards
|-
|}

== Links ==

[https://www.thedarkmod.com/missiondetails/?internalName=highex Official Mission List link]

You can download the mission directly while in game, by using the built-in TDM fan mission downloader.

Additional DL links:

* https://missions.thedarkmod.com/highex_84e60f7992ca1e51.pk4
* https://darkmod.taaaki.za.net/fmsv2/highex_84e60f7992ca1e51.pk4
* https://darkmod-alt02.taaaki.za.net/fms/highex_84e60f7992ca1e51.pk4
* https://tdm.frydrych.org/missions/highex_84e60f7992ca1e51.pk4
* http://mirror.mstrmnds.me/missions/highex_84e60f7992ca1e51.pk4

== Gallery ==

<gallery>
The Lieutenant 2 High Expectations (FM) promo 01.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 02.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 03.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 04.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 05.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 06.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 07.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 08.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 09.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 10.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 11.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 12.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 13.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 14.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 15.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 16.jpg|Promotional screenshot
</gallery>

== Discussions ==

*[https://forums.thedarkmod.com/index.php?/topic/21837-fan-mission-the-lieutenant-2-high-expectations-by-frost_salamander-20230424 TDM forums thread]

''Beware of potential spoilers !''

== Lootlists ==

TBA

== Walkthroughs ==

''Spoilers abound !''

'''Boy Lag'''
* [https://www.youtube.com/watch?v=ocLPBvEIqec Video playthrough - Part 1]
* [https://www.youtube.com/watch?v=KtSm9F3aBIU Video playthrough - Part 2]
* [https://www.youtube.com/watch?v=cbx_cbvtllQ Video playthrough - Part 3]
* [https://www.youtube.com/watch?v=V1R-LarggHo Video playthrough - Part 4]
* [https://www.youtube.com/watch?v=jjXv7fbJvAQ Video playthrough - Part 5]
* [https://www.youtube.com/watch?v=1XNs2J5DkUk Video playthrough - Part 6]
* [https://www.youtube.com/watch?v=8JluJnJM2OE Video playthrough - Part 7]

'''Onegin III'''
*[https://www.youtube.com/watch?v=i4UPXURwhaI Video playthrough]
*[https://www.youtube.com/watch?v=PBRHcmZqAMk Video playthrough] (Extra)

== Trivia ==

TBA

== External sites and reviews ==

*[https://www.thiefguild.com/fanmissions/39931/the-lieutenant-1-in-plain-sight Thief Guild.com FM overview and review]

== See also ==
* [https://www.thedarkmod.com/missions/ Official FMs list]
* [[Fan Missions for The Dark Mod]] - Main article on all of the published fan missions to date, in addition to the official list on the website.
* [[Fan Mission Series]] - An overview of all currently known series or campaigns of fan missions interconnected by their stories or characters. There are already plenty in TDM, and have been since its early days as an expandable game.
* [[Upcoming Fan Missions]] - An overview of Fan Missions in development or tentatively planned. (''Do not'' edit the overview.)
* [[Mission recommendation discussions]] - An overview of past discussions on what FMs the community recommends to players looking for various challenges (difficulty, size, theme, setting, objectives, etc.).
* [[Fan Mission Contests]] - An overview of past and present contests in Fan Mission creation, by members of the TDM community.

[[Category:Official FMs|The Lieutenant 2: High Expectations]]
[[Category:Missions by Frost_Salamander|The Lieutenant 2: High Expectations]]

The Lieutenant 2: High Expectations (FM)

2025-06-26T21:33:48Z

Frost Salamander: /* Series */

A fan mission for ''The Dark Mod''.

== Information ==

*'''Author:''' [[:Category:Missions by Frost_Salamander|Frost_Salamander]]
*'''Type:''' Single Mission
*'''Releases:''' 2023-04-24 (24 April 2023) - latest
*'''Version:''' 3
*'''Size:''' 42 MB
*'''EFX Reverb:''' Yes
*'''Subtitles:''' No

== Synopsis ==

''Follow the Lieutenant on his next mission to the City of Highborough.''

== Series ==

The FM is part of [[https://wiki.thedarkmod.com/index.php?title=Fan_Mission_Series#The_Lieutenant_series|The Lieutenant]] series.

== Theme / "Genre" / Setting ==

{|class="wikitable sortable mw-collapsible mw-collapsed" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=30% data-expandtext="Show" data-collapsetext="Hide"
|-
!bgcolor=#d0d0e0 width="5%"|Click to reveal spoiler...

|-
|Mansion/Estate
|-
|-
|City Missions
|-
|}

== Threats ==

{|class="wikitable sortable mw-collapsible mw-collapsed" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=30% data-expandtext="Show" data-collapsetext="Hide"
|-
!bgcolor=#d0d0e0 width="5%"|Click to reveal spoiler...

|-
|Guards
|-
|}

== Links ==

[https://www.thedarkmod.com/missiondetails/?internalName=highex Official Mission List link]

You can download the mission directly while in game, by using the built-in TDM fan mission downloader.

Additional DL links:

* https://missions.thedarkmod.com/highex_84e60f7992ca1e51.pk4
* https://darkmod.taaaki.za.net/fmsv2/highex_84e60f7992ca1e51.pk4
* https://darkmod-alt02.taaaki.za.net/fms/highex_84e60f7992ca1e51.pk4
* https://tdm.frydrych.org/missions/highex_84e60f7992ca1e51.pk4
* http://mirror.mstrmnds.me/missions/highex_84e60f7992ca1e51.pk4

== Gallery ==

<gallery>
The Lieutenant 2 High Expectations (FM) promo 01.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 02.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 03.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 04.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 05.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 06.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 07.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 08.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 09.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 10.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 11.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 12.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 13.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 14.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 15.jpg|Promotional screenshot
The Lieutenant 2 High Expectations (FM) promo 16.jpg|Promotional screenshot
</gallery>

== Discussions ==

*[https://forums.thedarkmod.com/index.php?/topic/21837-fan-mission-the-lieutenant-2-high-expectations-by-frost_salamander-20230424 TDM forums thread]

''Beware of potential spoilers !''

== Lootlists ==

TBA

== Walkthroughs ==

''Spoilers abound !''

'''Boy Lag'''
* [https://www.youtube.com/watch?v=ocLPBvEIqec Video playthrough - Part 1]
* [https://www.youtube.com/watch?v=KtSm9F3aBIU Video playthrough - Part 2]
* [https://www.youtube.com/watch?v=cbx_cbvtllQ Video playthrough - Part 3]
* [https://www.youtube.com/watch?v=V1R-LarggHo Video playthrough - Part 4]
* [https://www.youtube.com/watch?v=jjXv7fbJvAQ Video playthrough - Part 5]
* [https://www.youtube.com/watch?v=1XNs2J5DkUk Video playthrough - Part 6]
* [https://www.youtube.com/watch?v=8JluJnJM2OE Video playthrough - Part 7]

'''Onegin III'''
*[https://www.youtube.com/watch?v=i4UPXURwhaI Video playthrough]
*[https://www.youtube.com/watch?v=PBRHcmZqAMk Video playthrough] (Extra)

== Trivia ==

TBA

== External sites and reviews ==

*[https://www.thiefguild.com/fanmissions/39931/the-lieutenant-1-in-plain-sight Thief Guild.com FM overview and review]

== See also ==
* [https://www.thedarkmod.com/missions/ Official FMs list]
* [[Fan Missions for The Dark Mod]] - Main article on all of the published fan missions to date, in addition to the official list on the website.
* [[Fan Mission Series]] - An overview of all currently known series or campaigns of fan missions interconnected by their stories or characters. There are already plenty in TDM, and have been since its early days as an expandable game.
* [[Upcoming Fan Missions]] - An overview of Fan Missions in development or tentatively planned. (''Do not'' edit the overview.)
* [[Mission recommendation discussions]] - An overview of past discussions on what FMs the community recommends to players looking for various challenges (difficulty, size, theme, setting, objectives, etc.).
* [[Fan Mission Contests]] - An overview of past and present contests in Fan Mission creation, by members of the TDM community.

[[Category:Official FMs|The Lieutenant 2: High Expectations]]
[[Category:Missions by Frost_Salamander|The Lieutenant 2: High Expectations]]

Fan Mission Series

2025-06-26T21:32:03Z

Frost Salamander: /* The Lieutenant series */

This article serves as an overview of the known existing FM series.

Over the years, ''The Dark Mod'' has accumulated a number of Fan Missions that form a larger interconnected series or an overarching/continuing narrative. Many series are connected by their main characters, some by other FM inter-related elements.

The FMs of each series are sorted in chronological order.

The number of each FM includes a link to its page on the official website.

The name of each FM includes a link to its page on the official TDM wiki.

Beware of potential (minor) spoilers behind the character links.

== Official campaigns ==

While all TDM missions are technically Fan Missions, the ones belonging to these official campaigns are as close as TDM will ever get to its own official in-game missions, or in-game story campaigns. These core missions for the base game are in slow and patient continuous development (due to TDM being a hobbyist project of a fan community), and have been gradually added to the base game over the course of several years.

For additional series by TDM authors, please see the next section.

=== Introduction campaign ===

The missions of this campaign serve as a gradual introduction into the setting and gameplay of ''The Dark Mod''. The missions are shorter and fairly easy, and gradually put the player's newly acquired skills to the test.

Currently, this is the only series that is bundled directly as part of the base game. By installing TDM, the first three missions available to you will be part of this official mini-campaign.

'''Series' characters:''' [[Thief Characters#Corbin|Corbin]] (protagonist), Paschal Murnerus, Moorish adventurers (background)

'''Series' status:''' In development, but currently on hiatus. 3 missions currently available, including the (generally plotless) training mission.

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|0
!align=left|[[Training Mission (OM)|Training mission]]
|TDM dev team
|{{Forumlink|http://forums.thedarkmod.com/topic/9932-fan-mission-training-mission-20091017/}}
|2009-10-17 (original version)
|Training <br> Jumping/Platforming
|Unique. The official tutorial mission of TDM, with open-ended gameplay.
|-
|-
|1
!align=left|[[A New Job (OM)|A New Job]]
|Springheel
|{{Forumlink|http://forums.thedarkmod.com/topic/18647-tdm-205-official-introductory-missions/}}
|2017-03-14
|City Missions <br> Inn/Tavern
|
|-
|-
|2
!align=left|[[The Tears of Saint Lucia (OM)|The Tears of Saint Lucia]]
|TDM dev team
|{{Forumlink|http://forums.thedarkmod.com/topic/10579-fan-mission-the-tears-of-st-lucia-20081021/}} (original version), {{Forumlink|http://forums.thedarkmod.com/topic/18647-tdm-205-official-introductory-missions/}} (current version)
|2008-10-21 (original version), 2017-02-14 (current version, 3.0)
|Church/Cathedral
|[https://www.youtube.com/watch?v=yrGxoi3LSGg Briefing] <br> ''{{TDM-FM|15|standalone release link}}''
|-
|}

== Individual authors' series ==

The majority of missions created for ''The Dark Mod''. For the sake of easier searching, these FM series are arranged in alphabetical order, based on their titles. In terms of release, a Single-mission (S) series consists of several single-mission FM releases over time (the commonest sort), while a Campaign (C) series is an FM containing a storyline consisting of several missions.

=== ''The Accountant'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' [[Thief_Characters#Corbin|Corbin]] (protagonist)
* '''Series' status:''' Currently on hold.

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|ac1|1}}
!align=left|[[The Accountant 1: Thieves and Heirs (FM)|The Accountant 1: Thieves and Heirs]]
|[[:Category:Missions by Goldwell|Goldwell]]
|{{Forumlink|http://forums.thedarkmod.com/topic/19164-fan-mission-the-accountant-1-thieves-and-heirs-by-goldwell-20171108/}}
|2017-11-08
|Mansion/Estate
|[https://www.youtube.com/watch?v=Tk9DtOT4kjc Briefing]
|-

|-
|{{TDM-FM|ac2|2}}
!align=left|[[The Accountant 2: New in Town (FM)|The Accountant 2: New in Town]]
|[[:Category:Missions by Goldwell|Goldwell]]
|{{Forumlink|http://forums.thedarkmod.com/topic/18054-fan-mission-the-accountant-2-new-in-town-by-goldwell-20160509/}}
|2016-05-08
|Mansion/Estate
|[https://www.youtube.com/watch?v=xeuIO_GcYjQ Briefing] <br> [https://www.youtube.com/watch?v=w6e_SJ0_JOM Gameplay trailer]
|-
|}

=== ''Away'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:'''
* '''Series' status:''' Currently on hold. Planned to continue.

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-
|{{TDM-FM|away0|0}}
!align=left|[[Away 0: Stolen Heart (FM)|Away 0: Stolen Heart]]
|[[:Category:Missions by Geep|Geep]]
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20964-away-0-stolen-heart-by-geep-_atti_-20211112/}}
|2021-11-12
|Inn/Tavern, Jail/Prison, Museum Heist, Bank Job
|
|-
|{{TDM-FM|airpocket|1}}
!align=left|[[Away 1: Air Pocket (FM)|Away 1: Air Pocket]]
|[[:Category:Missions by Geep|Geep]]
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20252-fan-mission-away-1-air-pocket-by-geep-20200207/}}
|2020-02-06
|Pirate/Ship
|
|-
|}

=== ''Chronicles of Skulduggery'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' [[Thief_Characters#Elyas_Thorne|Elyas Thorne]] (protagonist)
* '''Series' status:''' TBA

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|cos0_thief|0}}
!align=left|[[Chronicles of Skulduggery 0: To Catch a Thief (FM)|To Catch a Thief]]
|[[:Category:Missions by Bienie|Bienie]]
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21156-fan-mission-chronicles-of-skulduggery-0-to-catch-a-thief-20211120/}}
|2021-11-20
|City Missions Mansion/Estate
|
|-
|-
|{{TDM-FM|127|1}}
!align=left|[[Chronicles of Skulduggery 1: Pearls and Swine (FM)|Pearls and Swine]]
|[[:Category:Missions by Bienie|Bienie]]
|{{Forumlink|https://forums.thedarkmod.com/topic/19439-chronicles-of-skulduggery-pearls-and-swine/}}
|2018-05-25
|City Missions
|
|-
|-
|{{TDM-FM|137|2}}
!align=left|[[Chronicles of Skulduggery 2: A Precarious Position (FM)|A Precarious Position]]
|[[:Category:Missions by Bienie|Bienie]]
|{{Forumlink|https://forums.thedarkmod.com/topic/19975-fan-mission-chronicles-of-skulduggery-2-a-precarious-position-20190504/}}
|2019-05-03
|City Missions
|
|-
|-
|{{TDM-FM|149|3}}
!align=left|[[Chronicles of Skulduggery 3: Sacricide (FM)|Sacricide]]
|[[:Category:Missions by Bienie|Bienie]]
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20483-fan-mission-chronicles-of-skulduggery-3-sacricide-20200718/}}
|2020-07-18
|City Missions
|
|-
|}

=== ''Corbin'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' [[Thief_Characters#Corbin|Corbin]] (protagonist), cardinal Laurenti (background), Keshka brotherhood members (antagonists)
* '''Series' status:''' TBA

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|builders_influence|1}}
!align=left|[[The Builder's Influence (FM)|The Builder's Influence]]
|[[:Category:Missions by RailGun|RailGun]], [[:Category:Missions by Springheel|Springheel]]
|{{Forumlink|http://forums.thedarkmod.com/topic/10811-fan-mission-the-builders-influence-20100320/}}
|2010-03-20 (original version), 2010-03-23 (version 2.0)
|Castle/Fortress
|
|-
|-
|{{TDM-FM|score_to_settle|2}}
!align=left|[[A Score to Settle (FM)|A Score to Settle]]
|[[:Category:Missions by Springheel|Springheel]]
|{{Forumlink|http://forums.thedarkmod.com/topic/12894-fan-mission-48-a-score-to-settle-by-springheel-20110701/}}
|2011-07-01
|City Missions
|
|-
|-
|{{TDM-FM|follow|3}}
!align=left|[[A Reputation to Uphold (FM)|A Reputation to Uphold]]
|[[:Category:Missions by Springheel|Springheel]]
|{{Forumlink|http://forums.thedarkmod.com/topic/16204-fan-mission-a-reputation-to-uphold-by-springheel/}}
|2014-04-18
|City Missions
|
|-
|-
|{{TDM-FM|matterofhours|4}}
!align=left|[[A Matter of Hours (FM)|A Matter of Hours]]
|[[:Category:Missions by Springheel|Springheel]]
|{{Forumlink|http://forums.thedarkmod.com/topic/18809-fan-mission-a-matter-of-hours-by-springheel-2842017/}}
|2017-04-28
|Warehouse
|
|-
|}

=== ''Crucible of Omens'' series ===

* '''Description:''' Though originally planned as a major campaign for future releases of TDM, development progress has been halted.
* '''Release:''' Released as Single-mission (S), possibly would have been a Campaign (C) if finished.
* '''Series' status:''' Development halted, campaign apparently cancelled. Only 1 mission has been completed and made available.

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|bcd|1}}
!align=left|[[Crucible of Omens: Behind Closed Doors (FM)|Crucible of Omens: Behind Closed Doors]]
|[[:Category:Missions by Bikerdude|Bikerdude]], Crucible of Omens Team
|{{Forumlink|http://forums.thedarkmod.com/topic/17627-crucible-of-omens-behind-closed-doors-by-bikerdude-the-crucible-team-updated-18122015/}}
|2015-12-19
|City Missions
|-
|}

=== ''Duncan Lynch'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' [[Thief_Characters#Duncan_Lynch|Duncan Lynch]] (protagonist)
* '''Series' status:''' TBA

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|factoryheist|1}}
!align=left|[[The Factory Heist (FM)|The Factory Heist]]
|[[:Category:Missions by thebigh|thebigh]]
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20562-the-factory-heist-12-sep-2020/}}
|2020-09-12
|Warehouse
|
|-
|-
|{{TDM-FM|housecall|2}}
!align=left|[[A House Call (FM)|A House Call]]
|[[:Category:Missions by thebigh|thebigh]]
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21329-a-house-call-by-thebigh-mar-10-2022/}}
|2022-03-10
|Mansion/Estate
|
|-
|-
|{{TDM-FM|delisle|3}}
!align=left|[[The House of deLisle (FM)|The House of deLisle]]
|[[:Category:Missions by thebigh|thebigh]]
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22227-fan-mission-the-house-of-delisle/}}
|2023-10-01
|Mansion/Estate, City Missions
|
|-
|}

=== ''The Hare in the Snare'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:'''
* '''Series' status:''' Planned to continue.

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|hareinthesnare|1}}
!align=left|[[The Hare in the Snare: Part 1 (FM)|The Hare in the Snare: Part 1]]
|[[:Category:Missions by Frost_Salamander|Frost_Salamander]] & [[:Category:Missions by Kerry000|Kerry000]]
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20883-fan-mission-the-hare-in-the-snare-part-1}}
|2021-04-09
|City Missions <br> Inn/Tavern
|
|-
|}

=== ''Hidden Hands'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' TBA
* '''Series' status:''' TBA

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|hhi|1}}
!align=left|[[Hidden Hands 1: Initiation (FM)|Initiation]]
|[[:Category:Missions by JackFarmer|JackFarmer]]
|{{Forumlink|http://forums.thedarkmod.com/index.php?/topic/19796-hidden-hands-initiation-27122018/}}
|2018-12-27
|Mansion/Estate <br> Ship
|
|-
|-
|{{TDM-FM|hhvf|2}}
!align=left|[[Hidden Hands 2: Vitalic Fever (FM)|Vitalic Fever]]
|[[:Category:Missions by JackFarmer|JackFarmer]]
|{{Forumlink|http://forums.thedarkmod.com/index.php?/topic/20051-hidden-hands-vitalic-fever-20072019/}}
|2019-07-20
|Mansion/Estate
|
|-
|-
|{{TDM-FM|hhtlc|3}}
!align=left|[[Hidden Hands 3: The Lost Citadel (FM)|The Lost Citadel]]
|[[:Category:Missions by JackFarmer|JackFarmer]]
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20490-hidden-hands-the-lost-citadel-23072020}}
|2020-07-23
|Castle/Fortress
|
|-
|-
|-
|{{TDM-FM|hhta|4}}
!align=left|[[Hidden Hands 4: The Anomaly (FM)|The Anomaly]]
|[[:Category:Missions by JackFarmer|JackFarmer]]
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20909-hidden-hands-the-anomaly}}
|2021-05-01
|Castle/Fortress <br> Forest
|
|-
|-
|}

=== ''In A Time of Need'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' [[Thief_Characters#Terry|Terry]] (supporting)
* '''Series' status:''' TBA

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|timeofneed|1}}
!align=left|[[In A Time of Need 1 (FM)|In A Time Of Need]]
|[[:Category:Missions by Kyyrma|Kyyrma]]
|{{Forumlink|http://forums.thedarkmod.com/topic/15354-fan-mission-in-a-time-of-need-by-kyyrma-20131112/}}
|2013-11-12
|Mansion/Estate
|
|-

|-
|{{TDM-FM|breakingout|2}}
!align=left|[[In A Time of Need 2: Breaking Out the Fence (FM)|Breaking Out the Fence]]
|[[:Category:Missions by Kyyrma|Kyyrma]]
|{{Forumlink|http://forums.thedarkmod.com/topic/16091-fan-mission-breaking-out-the-fence-17032014-by-kyyrma/}}
|2014-03-17
|City Missions
|
|-
|}

=== ''Master thief Corso'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' [[Thief Characters#Corso|Corso]] (protagonist), [[Thief Characters#Mingus|Mingus]] (background, supporting)
* '''Series' status:''' On hiatus.

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|lockner|1}}
!align=left|[[Lockner Manor (FM)|Lockner Manor]]
|[[:Category:Missions by Buck28|buck28]]
|{{Forumlink|http://forums.thedarkmod.com/topic/16452-new-mission-lockner-manor/}}
|2014-08-02
|Mansion/Estate <br> Inn/Tavern
|
|-

|-
|{{TDM-FM|briarwood|2}}
!align=left|[[Briarwood Cathedral (FM)|Briarwood Cathedral]]
|[[:Category:Missions by Buck28|buck28]]
|{{Forumlink|http://forums.thedarkmod.com/topic/16644-briarwood-cathedral/}}
|2014-10-29
|Church/Cathedral <br> Horror
|Winner of the [[Fan Mission Contests#2014 Halloween Speed-build Contest|2014 Halloween Speed-build Contest]].
|-
|}

=== ''No Honor Among Thieves'' campaign ===

* '''Release:''' Campaign (C)
* '''Series' characters:''' TBA
* '''Series' status:''' TBA

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|nhat3|1}}
!align=left|[[No Honor Among Thieves (FM)|Politics]]
|[[:Category:Missions by Goldchocobo|Goldchocobo]], [[:Category:Missions by RailGun|RailGun]], [[:Category:Missions by Mortem Desino|Mortem Desino]], [[:Category:Missions by Bikerdude|Bikerdude]]
|{{Forumlink|http://forums.thedarkmod.com/topic/10993-fan-mission-no-honor-among-thieves-20100429/}}
|2010-04-29 (original version), 2015-05-30 (current version, 3.0)
|Church/Cathedral
|
|-

|-
|{{TDM-FM|nhat3|2}}
!align=left|[[No Honor Among Thieves (FM)|A Night Out on the Town]]
|[[:Category:Missions by Goldchocobo|Goldchocobo]], [[:Category:Missions by RailGun|RailGun]], [[:Category:Missions by Mortem Desino|Mortem Desino]], [[:Category:Missions by Bikerdude|Bikerdude]]
|{{Forumlink|http://forums.thedarkmod.com/topic/10993-fan-mission-no-honor-among-thieves-20100429/}}
|2010-04-29 (original version), 2015-05-30 (current version, 3.0)
|City Missions
|
|-

|-
|{{TDM-FM|nhat3|3}}
!align=left|[[No Honor Among Thieves (FM)|No Honor Among Anyone <br> (a.k.a. Forest)]]
|[[:Category:Missions by Goldchocobo|Goldchocobo]], [[:Category:Missions by RailGun|RailGun]], [[:Category:Missions by Mortem Desino|Mortem Desino]], [[:Category:Missions by Bikerdude|Bikerdude]]
|{{Forumlink|http://forums.thedarkmod.com/topic/10993-fan-mission-no-honor-among-thieves-20100429/}}
|2010-04-29 (original version), 2015-05-30 (current version, 3.0)
|Outdoor/Pagan, Mansion/Estate
|
|-
|}

=== ''Of Brambles and Thorns'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' TBA
* '''Series' status:''' TBA

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|onesteptoofar|1}}
!align=left|[[One Step Too Far (FM)|One Step Too Far]]
|[[:Category:Missions by Dragofer|Dragofer]]
|{{Forumlink|http://forums.thedarkmod.com/topic/16457-fan-mission-one-step-too-far-by-dragofer-20140804/}}
|2014-08-04
|Pirate <br> Horror
|
|-

|-
|{{TDM-FM|river|2}}
!align=left|[[Down by the Riverside (FM)|Down by the Riverside]]
|[[:Category:Missions by Dragofer|Dragofer]]
|{{Forumlink|http://forums.thedarkmod.com/topic/18402-fan-mission-down-by-the-riverside-by-dragofer-20160925/}}
|2016-09-25
|Mansion/Estate <br> Ship
|
|-
|}

=== ''Penny Dreadful'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' Gerald Foxley (protagonist)
* '''Series' status:''' TBA

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|penny1_1|1}}
!align=left|[[Penny Dreadful 1: The Grail of Regrets (FM)|Penny Dreadful 1: The Grail of Regrets]]
|[[:Category:Missions by Melan|Melan]]
|{{Forumlink|http://forums.thedarkmod.com/topic/14952-fan-mission-penny-dreadful-by-melan-20130728/}}
|2013-07-27
|Horror
|
|-
|-
|{{TDM-FM|penny2_1|2}}
!align=left|[[Penny Dreadful 2: All the Way Up (FM)|Penny Dreadful 2: All the Way Up]]
|[[:Category:Missions by Melan|Melan]], [[:Category:Missions by Bikerdude|Bikerdude]]
|{{Forumlink|http://forums.thedarkmod.com/topic/16387-fan-mission-penny-dreadful-2-by-melan-and-bikerdude-2014078/}}
|2014-07-08
|Thieves' Highway (Rooftop)
|[https://www.youtube.com/watch?v=WmPfCfbeWvg Trailer]
|-
|-
|{{TDM-FM|penny3|3}}
!align=left|[[Penny Dreadful 3: Erasing the Trail (FM)|Penny Dreadful 3: Erasing the Trail]]
|[[:Category:Missions by Melan|Melan]], [[:Category:Missions by Bikerdude|Bikerdude]]
|{{Forumlink|http://forums.thedarkmod.com/topic/18200-fan-mission-penny-dreadful-3-by-melan-and-bikerdude-20160710/}}
|2016-07-09
|City Missions
|
|-
|}

=== ''Quinn Co.'' campaign ===

* '''Release:''' Campaign (C) (originally single mission (S))
* '''Series' characters:''' TBA
* '''Series' status:''' Completed and released.

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|quinn|1}}
!align=left|[[Quinn Co. (FM)|La Banque Bienveillante]]
|[[:Category:Missions by Airship Ballet|Airship Ballet]]
|{{Forumlink|http://forums.thedarkmod.com/topic/16702-fan-mission-la-banque-bienveillante-by-airship-ballet-20141122/}}
|2014-11-22 (original version), 2015-02-04 (current version, bundled with Chase Mercantile)
|Bank Jobs
|
|-
|-
|{{TDM-FM|quinn|2}}
!align=left|[[Quinn Co. (FM)|Chase Mercantile]]
|[[:Category:Missions by Airship Ballet|Airship Ballet]]
|{{Forumlink|http://forums.thedarkmod.com/topic/16912-fan-mission-chase-mercantile-by-airship-ballet-20150204/}}
|2015-02-04 (now bundled with La Banque Bienveillante)
|Bank Jobs
|
|-
|}

=== ''Sam Wilson'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' [[Thief_Characters#Sam Wilson|Samuel "Sam" Wilson]] (protagonist)
* '''Series' status:''' Ongoing.

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|sw1_ebound|1}}
!align=left|[[Sam Wilson 1: Eastbound (FM)|Sam Wilson 1: Eastbound]]
|[[:Category:Missions by jonri|jonri]]
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21402-fan-mission-sam-wilson-1-eastbound-2022-05-07}}
|2022-05-07
|Train
|The first TDM FM to be set on a steam train.
|-
|}

=== ''Selis Woderose'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' [[Thief_Characters#Selis_Woderose|Selis Woderose]] (protagonist)
* '''Series' status:''' Currently on hiatus.

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|flakebridge|1}}
!align=left|[[Selis Woderose 1: Flakebridge Monastery (FM)|Flakebridge Monastery]]
|[[:Category:Missions by Jesps|Jesps]]
|{{Forumlink|http://forums.thedarkmod.com/topic/11991-fm-flakebridge-monastery-by-jesps/}}
|2010-12-05
|Church/Cathedral
|
|-
|-
|{{TDM-FM|rake_off|2}}
!align=left|[[Selis Woderose 2: Rake-off (FM)|Rake-off]]
|[[:Category:Missions by Jesps|Jesps]]
|{{Forumlink|http://forums.thedarkmod.com/topic/12846-fm-rake-off-19-06-2011/}}
|2011-06-19
|Castle/Fortress
|
|-
|}

=== ''Shadowcursed'' series ===

* '''Release:''' Single-mission (S) for the first mission and Campaign (C) for the second mission.
* '''Series' characters:''' [[Thief_Characters#Bolen|Bolen]] (protagonist)
* '''Series' status:''' Ongoing, currently on hiatus.
* '''Ancilliary materials:''' ''[http://www.amazon.com/Shadowcursed-ebook/dp/B00BYEW02M Shadowcursed]'' novella (e-book)

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|requiem|1}}
!align=left|[[Requiem (FM)|Requiem]]
|[[:Category:Missions by Moonbo|Moonbo]]
|{{Forumlink|http://forums.thedarkmod.com/topic/15101-fan-mission-requiem-by-gelo-moonbo-fleisher-2013106/}}
|2013-10-08
|Church/Cathedral <br> Lost Civilizations
|[https://web.archive.org/web/20160409012413/https://community.eidosmontreal.com/blogs/thief-mod-winners Winner] of the 2014 official ''[http://forums.thedarkmod.com/topic/15956-square-enix-and-amazoncom-announce-thief-mod-contest/ Thief Mod Competition]'' by Square Enix & Amazon.com.
|-
|-
|{{TDM-FM|ahouseoflockedsecrets|2}}
!align=left|[[A House of Locked Secrets (FM)|A House of Locked Secrets]]
|[[:Category:Missions by Moonbo|Moonbo]]
|{{Forumlink|http://forums.thedarkmod.com/topic/17163-fan-mission-a-house-of-locked-secrets-by-gelo-moonbo-fleisher-20150528/}}
|2015-05-29
|Church/Cathedral <br> Mansion/Estate
|[https://www.youtube.com/watch?v=f5NuTJEZ8VE Trailer]
|-
|}

=== ''Shadows of Northdale'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' [[Thief Characters#Corbin|Corbin]] (protagonist)
* '''Series' status:''' Ongoing, currently in gradual development.

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|northdale1|1}}
!align=left|[[Shadows of Northdale Act I (FM)|Shadows of Northdale ACT I: <br> A Curious Mind]]
|[[:Category:Missions by Goldwell|Goldwell]]
|{{Forumlink|http://forums.thedarkmod.com/topic/19368-fan-mission-shadows-of-northdale-act-i-by-goldwell-20180323/}}
|2018-03-23
|City Missions
|[https://www.youtube.com/watch?v=p4nP3lYd6wg Briefing]
|-

|-
|{{TDM-FM|northdale2|2}}
!align=left|[[Shadows of Northdale Act II (FM)|Shadows of Northdale ACT II: <br> Down the Rabbit Hole]]
|[[:Category:Missions by Goldwell|Goldwell]]
|{{Forumlink|http://forums.thedarkmod.com/topic/19936-fan-mission-shadows-of-northdale-act-ii-by-goldwell-20190320/}}
|2019-03-20
|City Missions
|[https://www.youtube.com/watch?v=KO-eIOX9nqI Briefing]
|-
|}

=== ''St Alban'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' TBA
* '''Series' status:''' TBA

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|caduceus|1}}
!align=left|[[St Alban 1: The Caduceus of St Alban (FM)|The Caduceus of St. Alban]]
|[[:Category:Missions by Bikerdude|Bikerdude]]
|{{Forumlink|http://forums.thedarkmod.com/topic/11644-the-caduceus-of-st-alban-vertical-fm-contest-entry-aug-8th-2010/}}
|2010-08-23 (original version), 2010-08-26 (version 1.5.5)
|Church/Cathedral
|
|-
|-
|{{TDM-FM|cathedral|2}}
!align=left|[[St Alban 2: St Albans Cathedral (FM)|St. Albans Cathedral]]
|[[:Category:Missions by Bikerdude|Bikerdude]]
|{{Forumlink|http://forums.thedarkmod.com/topic/16343-fan-mission-st-albans-cathedral-v20-11062014/}} (current, 2.0 version)
|2010-11-01 (original version), 2014-06-11 (version 2.0)
|Church/Cathedral
|
|-
|}

=== ''Talbot'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' Talbot
* '''Series' status:''' Ongoing, currently on hiatus.

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|returntothecity|1}}
!align=left|[[Talbot 2: Return to the City (FM)|Return to the City]]
|[[:Category:Missions by Melan|Melan]]
|{{Forumlink|http://forums.thedarkmod.com/topic/10509-fan-mission-return-to-the-city-by-melan-20100110/}} (original version), {{Forumlink|http://forums.thedarkmod.com/topic/12390-fan-mission-return-to-the-city-v2-01032011/}} (version 2.0)
|2010-01-10 (original version), 2015-01-03 (2.0), 2015-01-03 (current version, 3.0)
|City Missions
|Winner of the [[Fan Mission Contests#2009 Grand Christmas Contest|2009 Grand Christmas Contest]].
|-
|-
|{{TDM-FM|fauchard1_1|2}}
!align=left|[[Talbot 3: Fiasco at Fauchard Street (FM)|Fiasco at Fauchard Street]]
|[[:Category:Missions by Melan|Melan]]
|{{Forumlink|http://forums.thedarkmod.com/topic/12655-fan-mission-fiasco-at-fauchard-street-by-melan-20110501/}}
|2011-05-01
|Thieves' Highway (Rooftop)
|
|-
|}

'''''Note:''' [[Sir Talbot's Collateral (FM)|Sir Talbot's Collateral]] by Bikerdude and Baal is actually an unrelated mission, just with a similarly named character.''

=== ''The Lieutenant'' series ===

* '''Release:''' Single-mission (S)
* '''Description:''' The series follows the cases of an intelligence officer.
* '''Series' characters:''' The titular Lieutenant
* '''Series' status:''' Ongoing.

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-
|-
|{{TDM-FM|inplainsight|1}}
!align=left|[[The Lieutenant 1: In Plain Sight (FM)|The Lieutenant 1: In Plain Sight]]
|[[:Category:Missions by Frost_Salamander|Frost_Salamander]]
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21549-fan-mission-in-plain-sight-by-frost_salamander-20220807}}
|2022-08-07
|City Missions
|
|-
|-
|{{TDM-FM|highex|2}}
!align=left|[[The Lieutenant 2: High Expectations (FM)|The Lieutenant 2: High Expectations]]
|[[:Category:Missions by Frost_Salamander|Frost_Salamander]]
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21837-fan-mission-the-lieutenant-2-high-expectations-by-frost_salamander-20230424}}
|2023-04-24
|Mansion/Estate <br> City Missions
|
|-
|-
|{{TDM-FM|foreignaffaris|3}}
!align=left|[[The Lieutenant 3: Foreign Affairs (FM)|The Lieutenant 3: Foreign Affairs]]
|[[:Category:Missions by Frost_Salamander|Frost_Salamander]]
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22452-fan-mission-the-lieutenant-3-foreign-affairs-by-frost_salamander}}
|2024/11/08
|City Missions, Moorish Architecture
|
|-
|-
|{{TDM-FM|reciprocalgambit|4}}
!align=left|[[The Lieutenant 4: A Reciprocal Gambit (FM)|The Lieutenant 4: A Reciprocal Gambit]]
|[[:Category:Missions by Frost_Salamander|Frost_Salamander]]
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22945-fan-mission-the-lieutenant-4-a-reciprocal-gambit-by-frost_salamander}}
|2025-06-18
|City Missions, Mansion/Estate
|
|-
|}

=== ''Thief's Den'' series ===

* '''Release:''' Single-mission (S)
* '''Description:''' The ''de facto'' oldest FM series in ''The Dark Mod''. Follow the skillful thief Farrell as he navigates the criminal underworld of [[The City|Bridgeport]] and the surrounding world.
* '''Series' characters:''' [[Thief Characters#Farrell|Farrell]] (protagonist), [[Thief Characters#Sebastian_Creep|Sebastian Creep]] (supporting)
* '''Series' status:''' Currently on hiatus.

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-
|-
|{{TDM-FM|thiefsden|1}}
!align=left|[[Thief's Den 1: Thief's Den (FM)|Thief's Den]]
|[[:Category:Missions by Fidcal|Fidcal]], [[:Category:Missions by Greebo|Greebo]]
|{{Forumlink|http://forums.thedarkmod.com/topic/11347-fan-mission-thiefs-den-re-release-by-fidcal20100704/}}
|2008-01-18 (original version), 2010-07-04 (version 2.0)
|City Missions
|
|-
|-
|{{TDM-FM|chalice1_1|2}}
!align=left|[[Thief's Den 2: The Chalice of Kings (FM)|The Chalice of Kings]]
|[[:Category:Missions by Fidcal|Fidcal]] (original version), [[:Category:Missions by Bikerdude|Bikerdude]], [[:Category:Missions by Xarg|Xarg]] (edits, version 2.0)
|{{Forumlink|http://forums.thedarkmod.com/topic/9935-fan-mission-chalice-of-kings-by-fidcal-20091017/}}
|2009-10-15 (original version), 2015-09-24 (version 2.0)
|Castle/Fortress
|
|-
|-
|{{TDM-FM|heartv2|3}}
!align=left|[[Thief's Den 3: The Heart of Lone Salvation (FM)|The Heart of Lone Salvation]]
|[[:Category:Missions by Fidcal|Fidcal]], Baddcog, [[:Category:Missions by Bikerdude|Bikerdude]]
|{{Forumlink|http://forums.thedarkmod.com/topic/10878-fan-mission-the-heart-of-lone-salvation-by-fidcal-baddcog-bikerdude-20100402/}}
|2010-04-02 (original version), 2014-04-12 (version 2.0)
|City Missions
|
|-
|-
|{{TDM-FM|alchemist|4}}
!align=left|[[Thief's Den 4: The Alchemist (FM)|The Alchemist]]
|[[:Category:Missions by Sotha|Sotha]], [[:Category:Missions by Fidcal|Fidcal]]
|{{Forumlink|http://forums.thedarkmod.com/topic/11170-fan-mission-the-alchemist-by-sotha-fidcal20100601/}}
|2010-06-01 (original version) 2010-06-04 (update)
|City Missions
|
|-
|}

=== ''Thomas Porter'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' [[Thief_Characters#Thomas Porter|Thomas Porter]] (protagonist), [[Thief_Characters#Lark Butternose|Lark Butternose]] (supporting), [[Noble/Wealthy_Characters#Godfrey_Knighton|Godfrey Knighton]] (background)
* '''Series' status:''' Concluded.
* '''Overview:''' [http://forums.thedarkmod.com/topic/15179-the-thomas-porter-series/ Courtesy of] Sotha.

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|mandrasola|1}}
!align=left|[[Thomas Porter 1: Mandrasola (FM)|Mandrasola]]
|[[:Category:Missions by Sotha|Sotha]]
|{{Forumlink|http://forums.thedarkmod.com/topic/12575-fan-mission-mandrasola-by-sotha-20110410/}}
|2011-04-10
|City Missions
|
|-
|-
|{{TDM-FM|knighton_manor|2}}
!align=left|[[Thomas Porter 2: Knighton Manor (FM)|Knighton Manor]]
|[[:Category:Missions by Sotha|Sotha]]
|{{Forumlink|http://forums.thedarkmod.com/topic/11898-fan-mission-the-knighton-manor-by-sotha-20101109/}}
|2010-11-09
|Mansion/Estate
|
|-
|-
|{{TDM-FM|beleaguered_fence|3}}
!align=left|[[Thomas Porter 3: The Beleaguered Fence (FM)|The Beleaguered Fence]]
|[[:Category:Missions by Sotha|Sotha]]
|{{Forumlink|http://forums.thedarkmod.com/topic/11298-fan-mission-the-beleaguered-fence-by-sotha-20100623/}}
|2010-06-23
|Jail/Prison
|
|-
|-
|{{TDM-FM|glenham_tower|4}}
!align=left|[[Thomas Porter 4: Glenham Tower (FM)|Glenham Tower]]
|[[:Category:Missions by Sotha|Sotha]]
|{{Forumlink|http://forums.thedarkmod.com/topic/11423-fan-mission-the-glenham-tower-by-sotha-20100717/}}
|2010-07-17
|Castle/Fortress <br> Horror
|Winner of the [[Fan_Mission_Contests#2010_Summer_Vertical_Contest|2010 Summer Vertical Contest]].
|-
|-
|{{TDM-FM|transaction|5}}
!align=left|[[Thomas Porter 5: The Transaction (FM)|The Transaction]]
|[[:Category:Missions by Sotha|Sotha]]
|{{Forumlink|http://forums.thedarkmod.com/topic/12408-fan-mission-the-transaction-by-sotha-20110304/}}
|2011-03-04
|City Missions
|
|-
|-
|{{TDM-FM|phrase_book|6}}
!align=left|[[Thomas Porter 6: The Phrase Book (FM)|The Phrase Book]]
|[[:Category:Missions by Sotha|Sotha]]
|{{Forumlink|http://forums.thedarkmod.com/topic/13799-fan-mission-the-phrase-book-by-sotha-20120512/}}
|2012-05-11
|City Missions <br> Thieves' Highway (Rooftop)
|
|-
|-
|{{TDM-FM|lich_queens_demise|7}}
!align=left|[[Thomas Porter 7: The Lich Queen's Demise (FM)|The Lich Queen's Demise]]
|[[:Category:Missions by Sotha|Sotha]]
|{{Forumlink|http://forums.thedarkmod.com/topic/14826-fan-mission-the-lich-queens-demise-by-sotha-20130520/}}
|2013-05-20
|Horror
|
|-
|}

=== ''Ulysses'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' Ulysses (protagonist)
* '''Series' status:''' TBA

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|ulysses_genesis|1}}
!align=left|[[Ulysses 1: Genesis (FM)|Ulysses: Genesis]]
|[[:Category:Missions by Sotha|Sotha]]
|{{Forumlink|http://forums.thedarkmod.com/topic/16428-fan-mission-ulysses-genesis-by-sotha-20140724/}}
|2014-07-24
|Mansion/Estate
|
|-

|-
|{{TDM-FM|u2_flock|2}}
!align=left|[[Ulysses 2: Protecting the Flock (FM)|Ulysses: Protecting the Flock]]
|[[:Category:Missions by Sotha|Sotha]]
|{{Forumlink|http://forums.thedarkmod.com/topic/17162-fan-mission-ulysses-2-protecting-the-flock-by-sotha-20150528/}}
|2015-05-28
|Church/Cathedral
|
|-
|}

=== ''Vengeance for a Thief'' campaign ===

* '''Release:''' Single-mission (S) for the first two published missions, Campaign (C) for the final release that also includes a new first mission.
* '''Series' characters:''' TBA
* '''Series' status:''' TBA

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|vfat3|1}}
!align=left|[[Vengeance for a Thief (FM)|The Angel's Tear]]
|[[:Category:Missions by Sir Taffsalot|Sir Taffsalot]]
|{{Forumlink|http://forums.thedarkmod.com/topic/16953-the-complete-vengeance-for-a-thief-campaign/}}
|2015-02-16
|Church/Cathedral
|
|-

|-
|{{TDM-FM|vfat1|2}}
!align=left|[[Vengeance for a Thief (FM)|A Pawn in the Game]]
|[[:Category:Missions by Sir Taffsalot|Sir Taffsalot]]
|{{Forumlink|http://forums.thedarkmod.com/topic/14068-fan-mission-vengeance-for-a-thief-part-1-by-sir-taffsalot-06092012/}}
|2012-09-06
|Jail/Prison
|''{{TDM-FM|62|standalone release link}}''
|-

|-
|{{TDM-FM|vfat2|3}}
!align=left|[[Vengeance for a Thief (FM)|The Art of Revenge]]
|[[:Category:Missions by Sir Taffsalot|Sir Taffsalot]]
|{{Forumlink|http://forums.thedarkmod.com/topic/15051-fan-mission-vengeance-for-a-thief-part-2-by-sir-taffsalot-06092013/}}
|2013-09-06
|Museum Heists
|''{{TDM-FM|75|standalone release link}}''
|-

|}

=== ''Volta'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' TBA
* '''Series' status:''' TBA

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|volta1_3|1}}
!align=left|[[Volta I: The Stone (FM)|Volta and the Stone]]
|[[:Category:Missions by Kingsal|Kingsal]]
|{{Forumlink|http://forums.thedarkmod.com/topic/18087-fan-mission-volta-and-the-stone-by-kingsal-05262016/}}
|2016-05-27
|Mansion/Estate <br> City Missions
|
|-

|-
|{{TDM-FM|cauldron_v2_2|2}}
!align=left|[[Volta II: Cauldron of the Gods (FM)|Volta 2: Cauldron of the Gods]]
|[[:Category:Missions by Kingsal|Kingsal]]
|{{Forumlink|http://forums.thedarkmod.com/topic/19207-fan-mission-volta-ii-cauldron-of-the-gods-by-kingsal-113017-update-v20/}}
|2017-11-30
|Lost Civilizations
|[https://www.youtube.com/watch?v=SRRCRVFHruc Briefing]
|-
|}

=== ''William Steele'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' [[Thief_Characters#William_Steele|William Steele]] (protagonist)
* '''Series' status:''' Concluded.

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|ws1_north|1}}
!align=left|[[William Steele 1: In the North (FM)|In the North]]
|[[:Category:Missions by Grayman|grayman]]
|{{Forumlink|http://forums.thedarkmod.com/topic/14214-fan-mission-in-the-north-by-grayman-20121020/}}
|2012-10-20
|Mansion/Estate
|
|-

|-
|{{TDM-FM|ws2_homeagain|2}}
!align=left|[[William Steele 2: Home Again (FM)|Home Again]]
|[[:Category:Missions by Grayman|grayman]]
|{{Forumlink|http://forums.thedarkmod.com/topic/15919-fan-mission-home-again-by-grayman-2014212/}}
|2014-02-12
|Thieves' Highway (Rooftop)
|
|-

|-
|{{TDM-FM|ws3_cleighmoor|3}}
!align=left|[[William Steele 3: Cleighmoor (FM)|Cleighmoor]]
|[[:Category:Missions by Grayman|grayman]]
|{{Forumlink|http://forums.thedarkmod.com/topic/16011-fan-mission-cleighmoor-by-grayman-201431/}}
|2014-03-01
|Sewers <br> Jail/Prison
|
|-

|-
|{{TDM-FM|ws4_warrens|4}}
!align=left|[[William Steele 4: The Warrens (FM)|The Warrens]]
|[[:Category:Missions by Grayman|grayman]]
|{{Forumlink|http://forums.thedarkmod.com/topic/19618-fan-mission-the-warrens-by-grayman-201891/}}
|2018-09-01
|City Missions
|
|-

|-
|{{TDM-FM|ws5_commerce|5}}
!align=left|[[William Steele 5: Commerce Bank (FM)|Commerce Bank]]
|[[:Category:Missions by Grayman|grayman]]
|{{Forumlink|http://forums.thedarkmod.com/topic/19957-fan-mission-commerce-bank-by-grayman-2019410/}}
|2019-04-10
|Bank Jobs
|
|-

|}

== Note ==

For a key to the descriptions of each Mission Type, please see [[Fan_Missions_for_The_Dark_Mod#Table_notes|this overview]].

== See also ==

*[[Fan Missions for The Dark Mod]] - Main article on TDM fan missions.

[[Category:Fan Missions|S]]

Fan Missions for The Dark Mod

2025-06-26T21:25:07Z

Frost Salamander: /* Missions table */

__NOTOC__
{{infobox|<center><br>'''Big Ugly Disclaimer:'''</center><br> '''The Dark Mod''' team does not necessarily support or endorse content listed here, and only hosts missions listed on the '''[https://www.thedarkmod.com/ official TDM website]'''. This is a community maintained list, and an ongoing work in progress. Most of the mirror links in this list are dead or are for missions that are not 2.0 compliant. Mission entries which are suspected to violate copyright must be text-only, and cannot contain links. Report and/or remove links found in violation of this rule.}}

* For details about editing this table, see [[#Editing_this_table|below]].
* For details about how to install Fan Missions please visit: [[Installing and Running Fan Missions]]
* To sort by a different criterion, click the [[Image:Sort none.gif]] icon in the relevant column header.

== Missions table ==
{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="19%"|Fan Mission Title
!bgcolor=#d0d0e0 width="14%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Links
!bgcolor=#d0d0e0 width="5%"|First Release
!bgcolor=#d0d0e0 width="2%"|Size (MB)
!bgcolor=#d0d0e0 width="2%"|EFX Reverb
!bgcolor=#d0d0e0 width="3%"|Translation Pack
!bgcolor=#d0d0e0 width="2%"|Sub - Titles
!bgcolor=#d0d0e0 width="10%"|Series
!bgcolor=#d0d0e0 width="16%"|Mission Type
!bgcolor=#d0d0e0 width="6%"|Spiders and Undead
|-



|-
!align=left|{{TDM-FM|crookshank|The Last Night on Crookshank Lane}}
|Jnon
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22947-fan-mission-the-last-night-on-crookshank-lane/}}
|2025-06-19
|77
|No
|No
|Yes
|
|City Missions, Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|lt4|The Lieutenant 4: A Reciprocal Gambit}}
|Frost_Salamander
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22945-fan-mission-the-lieutenant-4-a-reciprocal-gambit-by-frost_salamander/}}
|2025-06-18
|62
|Yes
|No
|No
|[[Fan_Mission_Series#The_Lieutenant_series|The Lieutenant]]
|City Missions, Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|footloose|Footloose museum theft}}
|Goblin of Akenash
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22654-fan-mission-footloose-museum-theft}}
|2025-02-05
|1.2
|No
|No
|No
|
|Museum Heist
|
|-

|-
!align=left|{{TDM-FM|scrooge|A Winter's Tale}} <br>(v1.4, 2025/01/13)
|Bikerdude
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22609-fan-mission-a-winters-tale-by-bikerdude-2024-11-30/}}
|2024-11-30
|140
|Yes
|No
|No
|[https://www.ttlg.com/forums/showthread.php?t=152747 TTLG Speed Jam]
|City Missions, Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|lastoffering|The Last Offering}}
|Sotha
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22594-fan-mission-the-last-offering-2024-11-16/}}
|2024-11-16
|2.7
|Yes
|No
|No
|
|Tombs, Catacombs & Crypts
|Horror Themes
|-

|-
!align=left|{{TDM-FM|gem_of_souls|Gem of Souls}}
|MirceaKitsune
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22583-fan-mission-gem-of-souls-31-10-2024/}}
|2024-10-31
|10
|Yes
|No
|No
|
|Church/Cathedral
|Undead, Horror Themes
|-

|-
!align=left|{{TDM-FM|pinnacle|Pinnacle: A Test of Talents}} <br>(v2.0, 2024/10/24)
|UncertainTitle, TwilitWitch
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22569-fan-mission-pinnacle-a-test-of-talents-hbd-tdm-15th-anniversary-contest/}}
|2024-10-17
|5
|No
|No
|No
|[[Fan_Mission_Contests#2024_15th_Anniversary_Contest|15YR]] Contest
|City Missions, Experimental
|
|-

|-
!align=left|{{TDM-FM|gemcutter|Volta 3: Gemcutter}}
|Kingsal
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22566-fan-mission-volta-iii-gemcutter-15th-anniversary-contest}}
|2024-10-16
|852
|Yes
|No
|Yes
|[[Fan_Mission_Contests#2024_15th_Anniversary_Contest|15YR]] '''WINNER'''<br> [[Fan_Mission_Series#Volta series|Volta]]
|Ship, City Missions, Moorish Architecture
|
|-

|-
!align=left|{{TDM-FM|yoft|You Only Fly Thrice}}
|DeTeEff
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22565-fan-mission-you-only-fly-thrice-by-deteeff-20241016/}}
|2024-10-16
|45
|Yes
|No
|Yes
|[[Fan_Mission_Contests#2024_15th_Anniversary_Contest|15YR]] Contest
|Ship <br> Experimental
|
|-

|-
!align=left|{{TDM-FM|wizt|The Wizard's Treasure}}
|thebigh
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22558-fan-mission-the-wizards-treasure-15th-anniversary-contest/}}
|2024-10-13
|7
|Yes
|No
|No
|[[Fan_Mission_Contests#2024_15th_Anniversary_Contest|15YR]] Contest
|Castle/Fortress
|
|-

|-
!align=left|{{TDM-FM|imperial_sword|The Imperial Sword}} <br>(v1.3.6, 2024/10/11)
|Bikerdude
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22541-fan-mission-the-imperial-sword-15yr-anniversary-contest/}}
|2024-09-21
|419
|Yes
|No
|Yes
|[[Fan_Mission_Contests#2024_15th_Anniversary_Contest|15YR]] Contest
|City Missions, Mansion/Estate
|Spiders
|-

|-
!align=left|{{TDM-FM|hhbam|Hidden Hands: Blood & Metal}} <br>(v4.0, 2024/11/29)
|JackFarmer
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22532-hidden-hands-blood-metal-campaign-01092024/}}
|2024-09-02
|1200
|Yes
|No
|Yes
|Hidden Hands 5
|
|Spiders, Undead, Horror Themes
|-

|-
!align=left|{{TDM-FM|faffairs|The Lieutenant 3: Foreign Affairs}} <br>(v4.0, 2024/11/08)
|Frost_Salamander
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22452-fan-mission-the-lieutenant-3-foreign-affairs-by-frost_salamander/}}
|2024-05-19
|501
|Yes
|No
|No
|[[Fan_Mission_Series#The_Lieutenant_series|The Lieutenant]]
|City Missions, Moorish Architecture
|
|-

|-
!align=left|{{TDM-FM|lookwhosmoving|Moving Day 2: Look Who's Moving Now}}
|wellingtoncrab
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22416-sad-news-%F0%9F%98%A2-but-fm-release/}}
|2024-04-01
|337
|No
|No
|No
|April Fools, <br>PTB (unofficial)
|Mansion/Estate, City Missions
|Humor
|-

|-
!align=left|{{TDM-FM|sneakandsouffle|Sneak & Soufflé}}
|Goldwell
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22417-fm-release-sneak-and-souffl%C3%A9-april-fools-mission-01042024/}}
|2024-04-01
|95
|Yes
|No
|No
|April Fools
|Mansion/Estate
|Humor
|-

|-
!align=left|{{TDM-FM|moongate|Moongate Ruckus}}
|Kingsal
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22419-having-trouble-sleeping-is-the-%F0%9F%8C%95moon-too-bright-the-%F0%9F%8E%BBmusic-too-loud-ive-got-an-fm-for-you/}}
|2024-04-01
|218
|Yes
|No
|No
|April Fools
|City Missions
|Humor
|-

|-
!align=left|{{TDM-FM|prize|Eye on the Prize}}
|Amadeus
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22418-fan-mission-eye-on-the-prize-412024/}}
|2024-04-01
|278
|No
|No
|Yes
|April Fools
|City Missions
|Humor
|-

|-
!align=left|{{TDM-FM|oldman|The Terrible Old Man}} <br>(v2.0, 2024/12/30)
|Ansome
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22393-fan-mission-the-terrible-old-man/}}
|2024-03-10
|11.7
|Yes
|No
|Yes
|
|Mansion/Estate, City Missions
|Horror Themes
|-

|-
!align=left|{{TDM-FM|sk_cooks|By The Cookbook}}<br>(v4.0 2024/07/08)
|Skaruts
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22357-fan-mission-by-the-cookbook/}}
|2024-02-02
|8.4
|No
|No
|No
|
|City Missions
|
|-

|-
!align=left|{{TDM-FM|altham|A Night in Altham}}
|joebarnin
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22296-fan-mission-a-night-in-altham/}}
|2023-12-05
|441
|Yes
|No
|Yes
|
|City Missions <br> Outdoor/Forest
|Spiders, Undead
|-

|-
!align=left|{{TDM-FM|spiderfinch|The Spider And The Finch}}<br>(v1.5.0 2024/07/11)
|GrodenVR
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22275-fan-mission-the-spider-and-the-finch-by-grodenglaive/}}
|2023-11-18
|45
|Yes
|No
|Yes
|
|Mansion/Estate <br> Outdoor/Forest
|Spiders
|-

|-
!align=left|{{TDM-FM|threepenny|The Threepenny Revue}}
|Jnon
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22229-fan-mission-the-threepenny-revue/}}
|2023-10-01
|21
|No
|No
|No
|
|City Missions
|
|-

|-
!align=left|{{TDM-FM|delisle|The House of deLisle}}
|thebigh
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22227-fan-mission-the-house-of-delisle/}}
|2023-10-01
|38
|Yes
|No
|No
|Duncan Lynch
|Mansion/Estate, City Missions
|Spiders, Undead, Body Horror
|-

|-
!align=left|{{TDM-FM|bridge2far|A Bridge Too Far}}
|cugzkani
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22220-fan-mission-a-bridge-too-far/}}
|2023-09-22
|6
|No
|No
|No
|
|City Missions
|
|-

|-
!align=left|{{TDM-FM|highex|The Lieutenant 2: High Expectations}}
|Frost_Salamander
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21837-fan-mission-the-lieutenant-2-high-expectations-by-frost_salamander-20230424}}
|2023-04-24
|34.9
|Yes
|No
|No
|[[Fan_Mission_Series#The_Lieutenant_series|The Lieutenant]]
|Mansion/Estate, City Missions
|
|-

|-
!align=left|{{TDM-FM|seeking|Seeking Lady Leicester}}
|Grayman, Bikerdude, Amadeus, Dragofer, WellingtonCrab
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21799-fan-mission-seeking-lady-leicester-by-grayman-3212023/}}
|2023-03-22
|493
|Yes
|No
|Yes
|
|Mansion/Estate, City Missions
|Undead, Horror Themes
|-

|-
!align=left|{{TDM-FM|inplainsight|The Lieutenant 1: In Plain Sight}}
|Frost_Salamander
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21549-fan-mission-in-plain-sight-by-frost_salamander-20220807}}
|2022-08-07
|14
|Yes
|No
|No
|[[Fan_Mission_Series#The_Lieutenant_series|The Lieutenant]]
|City Missions
|Undead, Horror Themes
|-

|-
!align=left|{{TDM-FM|at1_lucy|The Adventures of Thomas: Lucy's Quest}}
|gg
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21453-the-adventures-of-thomas-lucys-quest-2022-06-08}}
|2022-06-08
|484
|Yes
|No
|No
|Thomas 1
|City Missions
|Spiders, Undead, Horror Themes
|-

|-
!align=left|{{TDM-FM|wwtw|Who Watches the Watcher?}}
|DeTeEff (Fieldmedic)
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21434-fan-mission-who-watches-the-watcher-v10-by-deteeff-20220528}}
|2022-05-28
|86
|Yes
|No
|Yes
|
|City Missions
|Horror Themes
|-

|-
!align=left|{{TDM-FM|sw1_ebound|Sam Wilson 1: Eastbound}}
|jonri
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21402-fan-mission-sam-wilson-1-eastbound-2022-05-07}}
|2022-05-07
|18
|Yes
|No
|No
|Sam Wilson
|Train
|
|-

|-
!align=left|{{TDM-FM|byanyothername|By Any Other Name}}<br>(v3 2024/06/05)
|joebarnin
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21331-fan-mission-by-any-other-name-by-joebarnin-2022310/}}
|2022-03-10
|124
|Yes
|No
|Yes
|
|Mansion/Estate, City Missions
|
|-

|-
!align=left|{{TDM-FM|housecall|A House Call}}
|thebigh
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21329-a-house-call-by-thebigh-mar-10-2022/}}
|2022-03-10
|10
|Yes
|No
|No
|Duncan Lynch
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|nobleaffairs|Noble Affairs}}
|Goldwell
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21318-fan-mission-noble-affairs-by-goldwell-20220222-tdm-210-required/}}
|2022-02-22
|488
|Yes
|No
|No
|
|City Missions
|Horror Themes
|-

|-
!align=left|{{TDM-FM|iris|Iris}} <br>(v1.3, 2024/05/26)
|Wellingtoncrab
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21289-fan-mission-iris-by-wellingtoncrab-tdm-210-required-20220213/}}
|2022-02-13
|549
|Yes
|No
|No
|[[Fan_Mission_Contests#2022_Christmas_Connection_Contest|CCC 22]] - '''WINNER'''
|City Missions
|Horror Themes
|-

|-
!align=left|{{TDM-FM|ptb0|PtB 0: Moving Day}}
|Jedi_Wannabe
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21283-fan-mission-paying-the-bills-0-moving-day-tdm-210-beta-only-202228/}}
|2022-02-08
|160
|Yes
|No
|No
|[[Fan_Mission_Contests#2022_Christmas_Connection_Contest|CCC 22]], PTB
|Mansion/Estate <br> Outdoor/Forest
|Spiders
|-

|-
!align=left|{{TDM-FM|written|Written in Stone}}
|Bikerdude, Amadeus, Dragofer
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21265-written-in-stone-beta-210-only-20220128/}}
|2022-01-28
|338
|Yes
|No
|Yes
|[[Fan_Mission_Contests#2022_Christmas_Connection_Contest|CCC 22]], Elixir
|City Missions
|Undead, Horror Themes
|-

|-
!align=left|{{TDM-FM|hazard|Hazard Pay}}
|Kingsal
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21264-fan-mission-hazard-pay-by-kingsal-tdm-beta-210-only/}}
|2022-01-28
|404
|Yes
|No
|Yes
|[[Fan_Mission_Contests#2022_Christmas_Connection_Contest|CCC 22]]
|Tombs, Catacombs & Crypts
|Undead
|-

|-
!align=left|{{TDM-FM|newford|Down and Out on Newford Road}}
|thebigh
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21260-down-and-out-on-newford-road-by-thebigh-jan-26-2022-christmas-connections-contest-entry/}}
|2022-01-26
|17
|Yes
|No
|No
|[[Fan_Mission_Contests#2022_Christmas_Connection_Contest|CCC 22]]
|Church/Cathedral, City Missions
|Undead, Horror Themes
|-

|-
!align=left|{{TDM-FM|deadeye|Deadeye}}
|Sotha
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21225-fan-mission-deadeye-by-sotha-20211231/}}
|2021-12-31
|1.8
|Yes
|No
|No
|
|City Missions
|
|-

|-
!align=left|{{TDM-FM|black_mage|The Black Mage}}
|Grayman, JackFarmer
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21215-the-black-mage/}}
|2021-12-23
|410
|Yes
|No
|Yes
|
|Castle/Fortress <br><br>In memoriam of Grayman {{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20933-we-have-lost-a-member-of-the-tdm-development-team/}}
|Horror Themes
|-

|-
!align=left|{{TDM-FM|ch1_eaton|Cole Hurst 1: Eaton}}
|bwyan
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21170-fan-mission-cole-hurst-1-eaton-by-bwyan-20211202/}}
|2021-12-01
|41
|Yes
|No
|No
|Cole Hurst
|Mansion/Estate, City Missions
|
|-

|-
!align=left|{{TDM-FM|cos0_thief|Chronicles of Skulduggery 0: To Catch a Thief}}
|Bienie
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21156-fan-mission-chronicles-of-skulduggery-0-to-catch-a-thief-20211120/}}
|2021-11-20
|15
|Yes
|No
|No
|[[Fan_Mission_Series#Chronicles_of_Skulduggery_series|Chronicles of Skulduggery]]
|City Missions, Mansion/Estate
|Horror Themes
|-

|-
!align=left|{{TDM-FM|away0|Away 0 - Stolen Heart}}
|Geep,_Atti_
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20964-away-0-stolen-heart-by-geep-_atti_-20210924/}}
|2021-11-12
|189.5
|No
|No
|No
|[[Fan_Mission_Series#Away_series|Away]]
|Inn/Tavern, Jail/Prison, <br> Museum Heist, Bank Job
|
|-

|-
!align=left|{{TDM-FM|hhta|Hidden Hands: Anomaly}}
|JackFarmer
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20909-hidden-hands-the-anomaly}}
|2021-05-01
|532.7
|Yes
|No
|No
|[[Fan_Mission_Series#Hidden_Hands_series|Hidden Hands]]
|Castle/Fortress <br> Outdoor/Forest
|Undead, Spiders
|-

|-
!align=left|{{TDM-FM|hareinthesnare|The Hare in the Snare: Part 1}}
|Frost_Salamander,Kerry000
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20883-fan-mission-the-hare-in-the-snare-part-1}}
|2021-04-09
|102.3
|Yes
|No
|Yes
|Hare in the Snare 1
|City Missions <br> Inn/Tavern
|
|-

|-
!align=left|{{TDM-FM|blackgrove|Blackgrove Manor}}<br>(v1.02, 2021/04/24)
|ddaazzaa
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20844-fan-mission-blackgrove-manor-by-ddaazzaa-20210314/}}
|2021-03-14
|24.7
|Yes
|No
|No
|
|Mansion/Estate
|Undead, Horror Themes
|-

|-
!align=left|{{TDM-FM|scroll|Scroll of Remembrance}}
|MirceaKitsune
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20613-fan-mission-scroll-of-remembrance-by-mirceakitsune-03112020/}}
|2020-11-03
|16.2
|Yes
|No
|No
|
|Mansion/Estate
|Undead, Horror Themes
|-

|-
!align=left|{{TDM-FM|factoryheist|The Factory Heist}}
|thebigh
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20562-the-factory-heist-12-sep-2020/}}
|2020-09-12
|1.1
|No
|No
|No
|Duncan Lynch
|Warehouse
|
|-

|-
!align=left|{{TDM-FM|nowandthen|Now and Then}}<br>(v3.0. 2025/03/19)
|joebarnin
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20560-fan-mission-now-and-then-by-joebarnin-20200908/}}
|2020-09-08
|236.1
|Yes
|No
|Yes
|
|Museum Heists
|
|-

|-
!align=left|{{TDM-FM|hhtlc|Hidden Hands: The Lost Citadel}}
|JackFarmer
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20490-hidden-hands-the-lost-citadel-23072020}}
|2020-07-23
|444
|Yes
|No
|No
|[[Fan_Mission_Series#Hidden_Hands_series|Hidden Hands]]
|Castle/Fortress
|Undead
|-

|-
!align=left|{{TDM-FM|cos3_sacricide|Chronicles of Skulduggery 3: Sacricide}}
|Bienie
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20483-fan-mission-chronicles-of-skulduggery-3-sacricide-20200718/}}
|2020-07-18
|97.8
|Yes
|No
|No
|[[Fan_Mission_Series#Chronicles_of_Skulduggery_series|Chronicles of Skulduggery]]
|City Missions
|Undead
|-

|-
!align=left|{{TDM-FM|painterswife|The Painter's Wife}}<br>(v1.4, 2025/06/10)
|Fractured Glass Company
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20436-fan-mission-the-painter’s-wife-by-fractured-glass-company-20200701/}}
|2020-07-01
|205
|Yes
|No
|Yes
|
|City Missions
|Spiders, Undead
|-

|-
!align=left|{{TDM-FM|anol|A Night Of Loot: One Man's Treasure}}
|OGDA
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20416-fan-mission-a-night-of-loot-one-mans-treasure/}}
|2020-06-13
|3.9
|No
|No
|No
|
|Shop/House
|
|-

|-
!align=left|{{TDM-FM|good|A Good Neighbor}}
|Amadeus
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20292-fan-mission-a-good-neighbor/}}
|2020-03-08
|54.6
|Yes
|No
|No
|
|City Missions <br> Inn/Tavern
|
|-

|-
!align=left|{{TDM-FM|airpocket|Away 1 - Air Pocket}}
|Geep
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20252-fan-mission-away-1-air-pocket-by-geep-20200207}}
|2020-02-06
|15.3
|No
|No
|No
|[[Fan_Mission_Series#Away_series|Away]]
|Pirate <br> Ship
|
|-

|-
!align=left|{{TDM-FM|snowed_inn|Snowed Inn}}
|Goldwell and Kingsal
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20201-fan-mission-snowed-inn-by-goldwell-kingsal-20191225}}
|2019-12-25
|382
|Yes
|No
|No
|
|City Missions
|
|-

|-
!align=left|{{TDM-FM|indangerofjudgment|In Danger of Judgment}}
|krrg
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20155-fan-mission-in-danger-of-judgment-20191115/}}
|2019-11-15
|11.9
|No
|No
|No
|
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|lhl|Langhorne Lodge}}
|Bienie
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20143-fan-mission-langhorne-lodge/}}
|2019-10-30
|8.2
|Yes
|No
|No
|
|Mansion/Estate
|Undead <br> Ghosts <br> Spiders
|-

|-
!align=left|{{TDM-FM|heartstmattis|The Heart of Saint Mattis}}
|joebarnin
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20091-fan-mission-the-heart-of-saint-mattis-by-joebarnin-20190910/}}
|2019-09-10
|58.7
|Yes
|No
|No
|
|Church/Cathedral
|Spiders, Undead, Horror Themes
|-

|-
!align=left|{{TDM-FM|peril|Perilous Refuge}}
|Dragofer, Crucible Team
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20090-fan-mission-perilous-refuge-by-dragofer-20190910/}}
|2019-09-10
|34.7
|Yes
|No
|No
|
|Ship, City Missions
|
|-

|-
!align=left|{{TDM-FM|hhvf|Hidden Hands: Vitalic Fever}}<br>(v6, 2025/04/20)
|JackFarmer
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20051-hidden-hands-vitalic-fever-20072019}}
|2019-07-20
|269
|Yes
|No
|Yes
|[[Fan_Mission_Series#Hidden_Hands_series|Hidden Hands]]
|Mansion/Estate
|Spiders, Undead
|-

|-
!align=left|{{TDM-FM|cos2_precpos|Chronicles of Skulduggery 2: A Precarious Position}}
|Bienie
|{{Forumlink|https://forums.thedarkmod.com/topic/19975-fan-mission-chronicles-of-skulduggery-2-a-precarious-position-20190504/}}
|2019-05-04
|14.5
|Yes
|No
|No
|[[Fan_Mission_Series#Chronicles_of_Skulduggery_series|Chronicles of Skulduggery]]
|City Missions
|
|-

|-
!align=left|{{TDM-FM|ws5_commerce|William Steele 5: Commerce Bank}}
|grayman
|{{Forumlink|https://forums.thedarkmod.com/topic/19957-fan-mission-commerce-bank-by-grayman-2019410/}}
|2019-04-10
|30
|Yes
|No
|Yes
|[[Fan_Mission_Series#William_Steele_series|William Steele]]
|Bank Jobs
|
|-

|-
!align=left|{{TDM-FM|marshofrahena|Marsh of Rahena}}
|ERH+
|{{Forumlink|https://forums.thedarkmod.com/topic/19951-fan-mission-marsh-of-rahena-by-erh-201945}}
|2019-04-05
|60.3
|Yes
|No
|No
|
|Castle/Fortress, Horror
|Spiders, Undead, Horror Themes
|-

|-
!align=left|{{TDM-FM|northdale2|Shadows of Northdale ACT 2}}
|Goldwell
|{{Forumlink|https://forums.thedarkmod.com/topic/19936-fan-mission-shadows-of-northdale-act-ii-by-goldwell-20190320/}} [https://www.youtube.com/watch?v=KO-eIOX9nqI Briefing]
|2019-03-20
|417
|Yes
|No
|No
|[[Fan_Mission_Series#Shadows of Northdale series|Shadows of Northdale]]
|City Missions
|Undead
|-

|-
!align=left|{{TDM-FM|cleanneighbourhood|Cleaning Up the Neighbourhood}}
|some1stoleit and Bikerdude
|{{Forumlink|https://forums.thedarkmod.com/topic/19898-fan-mission-cleaning-up-the-neighbourhood-by-some1stoleitbikerdude-20190219/}}
|2019-02-18
|34.3
|No
|No
|No
|
|City Missions
|
|-

|-
!align=left|{{TDM-FM|hhi|Hidden Hands: Initiation}}
|JackFarmer
|{{Forumlink|https://forums.thedarkmod.com/topic/19796-hidden-hands-initiation-27122018/}}
|2018-12-27
|92.5
|Yes
|No
|No
|[[Fan_Mission_Series#Hidden_Hands_series|Hidden Hands]]
|Mansion/Estate <br>Ship
|Spiders, Extra-natural entities
|-

|-
!align=left|{{TDM-FM|reluctantbenefaction|The Night of Reluctant Benefaction}}
|Bienie
|{{Forumlink|https://forums.thedarkmod.com/topic/19787-fan-mission-the-night-of-reluctant-benefaction/}}
|2018-12-24
|11.9
|Yes
|No
|No
|
|City Missions
|
|-

|-
!align=left|{{TDM-FM|mercwarehouse|Mission of Mercy}}
|joebarnin
|{{Forumlink|https://forums.thedarkmod.com/topic/19642-fan-mission-mission-of-mercy-by-joebarnin-20180914/}}
|2018-09-14
|10.1
|No
|No
|No
|
|Warehouse
|
|-

|-
!align=left|{{TDM-FM|ws4_warrens|William Steele 4: The Warrens}}
|grayman
|{{Forumlink|https://forums.thedarkmod.com/topic/19618-fan-mission-the-warrens-by-grayman-201891/}}
|2018-09-01
|53
|Yes
|No
|Yes
|[[Fan_Mission_Series#William_Steele_series|William Steele]]
|City Missions
|
|-

|-
!align=left|{{TDM-FM|braeden_church|Braeden Church}}
|grayman
|{{Forumlink|https://forums.thedarkmod.com/topic/19533-fan-mission-braeden-church-by-grayman-201871/}}
|2018-07-01
|24
|No
|No
|Yes
|
|Mansion/Estate
|Undead
|-

|-
!align=left|{{TDM-FM|pearlsnswine|Chronicles of Skulduggery: Pearls and Swine}}
|Bienie
|{{Forumlink|https://forums.thedarkmod.com/topic/19439-chronicles-of-skulduggery-pearls-and-swine/}}
|2018-05-25
|23
|Yes
|No
|Yes
|[[Fan_Mission_Series#Chronicles_of_Skulduggery_series|Chronicles of Skulduggery]]
|City Missions
|
|-

|-
!align=left|{{TDM-FM|northdale1|Shadows of Northdale ACT I}}
|Goldwell
|{{Forumlink|https://forums.thedarkmod.com/topic/19368-fan-mission-shadows-of-northdale-act-i-by-goldwell-20180323/}} [https://www.youtube.com/watch?v=p4nP3lYd6wg Briefing]
|2018-03-23
|295
|Custom <br>(not EFX)
|No
|No
|[[Fan_Mission_Series#Shadows of Northdale series|Shadows of Northdale]]
|City Missions
|
|-

|-
!align=left|{{TDM-FM|sirt|Sir Taffsalot's Sword}}
|grayman
|{{Forumlink|https://forums.thedarkmod.com/topic/19361-fan-mission-sir-taffsalots-sword-by-grayman-2018318/}}
|2018-03-17
|11.3
|No
|No
|No
|
|Mansion/Estate <br> <br> In memoriam of Gary (Sir Taffsalot) {{Forumlink|https://forums.thedarkmod.com/topic/19306-sad-news-we-lost-one-of-our-own-sir-taffsalot/}}
|
|-

|-
!align=left|{{TDM-FM|arena|The Arena}}
|ERH+
|{{Forumlink|https://forums.thedarkmod.com/topic/19350-fan-mission-the-arena-by-erh/}}
|2018-03-12
|3
|No
|No
|No
|
|Arena Deathmatch <br> Experimental
|Spiders, Undead
|-

|-
!align=left|{{TDM-FM|elixir|The Elixir}}
|Bikerdude and Obsttorte
|{{Forumlink|https://forums.thedarkmod.com/topic/19323-fan-mission-the-elixir-by-b1k3rdude-obsttorte-17022018/}} [https://www.youtube.com/watch?v=KfElYZs-FaE Briefing]
|2018-02-17
|112
|Yes
|No
|Yes
|Elixir
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|cauldron_v2_2|Volta 2: Cauldron of the Gods}}
|Kingsal
|{{Forumlink|https://forums.thedarkmod.com/topic/19207-volta-ii-cauldron-of-the-gods/}} [https://www.youtube.com/watch?v=SRRCRVFHruc Briefing]
|2017-11-30
|252
|Yes
|No
|No
|[[Fan_Mission_Series#Volta series|Volta]]
|Lost Civilizations
|Undead
|-

|-
!align=left|{{TDM-FM|itb|In the Black}}
|VanishedOne
|{{Forumlink|https://forums.thedarkmod.com/topic/19185-fan-mission-in-the-black/}}
|2017-11-18
|103
|No
|No
|No
|
|Mansion/Estate
|Undead
|-

|-
!align=left|{{TDM-FM|ac1|Accountant 1: Thieves and Heirs}}
|Goldwell
|{{Forumlink|https://forums.thedarkmod.com/topic/19164-fan-mission-the-accountant-1-thieves-and-heirs-by-goldwell-20171108}} [https://www.youtube.com/watch?v=Tk9DtOT4kjc Briefing]
|2017-11-08
|247
|No
|Yes <br><br>(Darkfate version is better for Russian players, fully dubbed audio)
|No
|[[Fan_Mission_Series#The Accountant series|The Accountant]]
|Mansion/Estate
|Spiders
|-

|-
!align=left|{{TDM-FM|kotm|King of the Mountain}}
|Spoonman
|{{Forumlink|https://forums.thedarkmod.com/topic/19105-fan-mission-king-of-the-mountain-by-spoonman-18092017/}}
|2017-09-18
|8.07
|No
|No
|No
|
|Jail/Prison
|
|-

|-
!align=left|{{TDM-FM|briarwood_manor|Briarwood Manor}}
|NeonStyle
|{{Forumlink|https://forums.thedarkmod.com/topic/18980-fan-mission-briarwood-manor-by-neonsstyle-first-mission-2017-07-11}} [https://www.youtube.com/watch?v=BZnSuLVatYM Trailer] [https://www.youtube.com/watch?v=CPlu8fEzyGM Briefing]
|2017-07-11
|90
|No
|No
|No
|
|Mansion/Estate
|Spider
|-

|-
!align=left|{{TDM-FM|matterofhours|A Matter of Hours}}
|Springheel
|{{Forumlink|https://forums.thedarkmod.com/topic/18809-fan-mission-a-matter-of-hours-by-springheel-2842017/}}
|2017-04-28
|13
|No
|Yes
|No
|[[Fan Mission Series#Corbin series|Corbin]]
|Warehouse
|
|-

|-
!align=left|{{TDM-FM|ravine|The Ravine}}
|Spoonman
|{{Forumlink|https://forums.thedarkmod.com/topic/18782-fan-mission-the-ravine-by-spoonman-17042017/}}
|2017-04-17
|30.6
|No
|Yes
|No
|
|Outdoor/Pagan
|Spiders
|-

|-
!align=left|{{TDM-FM|bakery_job|The Bakery Job}}
|Sotha
|{{Forumlink|https://forums.thedarkmod.com/topic/18707-fan-mission-the-bakery-job-by-sotha-20170309/}}
|2017-03-09
|2
|No
|Yes
|No
|
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM||Mission 1: A New Job}}
|Springheel
|{{Forumlink|https://forums.thedarkmod.com/topic/18647-tdm-205-official-introductory-missions/}}
|2017-03-14
|13.8
|Yes
|
|Yes
|[[Fan_Mission_Series#Introduction_campaign|Official Campaign]]
|City Missions <br> Inn/Tavern
|
|-

|-
!align=left|{{TDM-FM|coercion|Coercion}}
|Sotha
|{{Forumlink|https://forums.thedarkmod.com/topic/18405-fan-mission-coercion-by-sotha-20160927}}
|2016-09-27
|10
|No
|Yes
|Yes
|
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|river|Down by the Riverside}}
|Dragofer
|{{Forumlink|https://forums.thedarkmod.com/topic/18402-fan-mission-down-by-the-riverside-by-dragofer-20160925}}
|2016-09-25
|56
|No
|No
|Yes
|[[Fan_Mission_Series#Of Brambles and Thorns series|Of Brambles and Thorns]]
|Mansion/Estate <br> Ship <br> Horror
|Horror themes, Undead
|-

|-
!align=left|{{TDM-FM|penny3|Penny Dreadful 3: Erasing the Trail}}
|Melan and Bikerdude
|{{Forumlink|https://forums.thedarkmod.com/topic/18200-fan-mission-penny-dreadful-3-by-melan-and-bikerdude-20160710}}
|2016-07-09
|200
|No
|No
|No
|[[Fan_Mission_Series#Penny Dreadful series|Penny Dreadful]]
|City Missions
|
|-

|-
!align=left|{{TDM-FM|volta1_3|Volta 1: Volta and the Stone}}
|Kingsal
|{{Forumlink|https://forums.thedarkmod.com/topic/18087-fan-mission-volta-and-the-stone-by-kingsal-05262016}}
|2016-05-27
|102
|Yes
|Yes
|No
|[[Fan_Mission_Series#Volta series|Volta]]
|Mansion/Estate <br> City Missions
|
|-

|-
!align=left|{{TDM-FM|fever|Full Moon Fever}}<br>(v2.0 2018/02/21)
|Spoonman
|{{Forumlink|https://forums.thedarkmod.com/topic/18066-fan-mission-full-moon-fever-by-spoonman-14052016/}}
|2016-05-14
|21
|No
|Yes
|No
|
|Mansion/Estate
|Undead
|-

|-
!align=left|{{TDM-FM|kingofdiamonds|King of Diamonds}}
|Spooks
|{{Forumlink|https://forums.thedarkmod.com/topic/18064-fan-mission-the-king-of-diamonds-by-spooks-20160513}}
|2016-05-13
|26.3
|No
|No
|No
|
|City Missions
|Occult themes
|-

|-
!align=left|{{TDM-FM|ac2|Accountant 2: New in Town}}
|Goldwell
|{{Forumlink|https://forums.thedarkmod.com/topic/18054-fan-mission-the-accountant-2-new-in-town-by-goldwell-20160509/}} [https://www.youtube.com/watch?v=xeuIO_GcYjQ Briefing] <br> [https://www.youtube.com/watch?v=w6e_SJ0_JOM Gameplay trailer]
|2016-05-08
|358
|No
|Yes
|No
|[[Fan_Mission_Series#The Accountant series|The Accountant]]
|Mansion/Estate
|Undead
|-

|-
!align=left|{{TDM-FM|cutpurse|The Smiling Cutpurse}}
|Airship Ballet
|{{Forumlink|https://forums.thedarkmod.com/topic/17850-fan-mission-the-smiling-cutpurse-by-airship-ballet-20160325/}}
|2016-03-25
|87
|No
|Yes
|No
|
|Mansion/Estate <br> Sewers
|
|-

|-
!align=left|{{TDM-FM|mother|Mother Rose}}
|grayman
|{{Forumlink|https://forums.thedarkmod.com/topic/17653-fan-mission-mother-rose-by-grayman-20160101/#entry385131/}}
|2016-01-01
|10
|No
|Yes
|No
|
|Mansion/Estate
|Ghost
|-

|-
!align=left|{{TDM-FM|bcd|Behind Closed Doors}}
|Bikerdude and the Crucible Team
|{{Forumlink|https://forums.thedarkmod.com/topic/17627-crucible-of-omens-behind-closed-doors-by-bikerdude-the-crucible-team-updated-18122015/}}
|2015-12-19
|359
|Yes
|Yes
|No
|[[Fan_Mission_Series#Crucible of Omens series|Crucible of Omens]]
|City Missions
|
|-

|-
!align=left|{{TDM-FM|theratst|The Rats Triumphant}}
|Melan
|{{Forumlink|https://forums.thedarkmod.com/topic/17512-fan-mission-the-rats-triumphant-by-melan-20151031/}}
|2015-10-31
|11
|No
|Yes
|No
|[[Fan_Mission_Contests#2015_Halloween_Speed-build_Contest|HSC 15]] '''WINNER'''
|City Missions
|Undead
|-

|-
!align=left|{{TDM-FM|deaddrunk|Dead Drunk}}
|Stumpy
|{{Forumlink|https://forums.thedarkmod.com/topic/17511-fan-mission-dead-drunk-by-stumpy-20151030/}}
|2015-10-30
|4
|No
|Yes
|No
|[[Fan_Mission_Contests#2015_Halloween_Speed-build_Contest|HSC 15]]
|Tombs, Catacombs & Crypts
|Undead
|-

|-
!align=left|{{TDM-FM|remorse|Thief's Remorse}}
|Airship Ballet
|{{Forumlink|https://forums.thedarkmod.com/topic/17509-fan-mission-thiefs-remorse-by-airship-ballet-20151030/}}
|2015-10-30
|42
|No
|Yes
|No
|[[Fan_Mission_Contests#2015_Halloween_Speed-build_Contest|HSC 15]]
|Tombs, Catacombs & Crypts
|Undead
|-

|-
!align=left|{{TDM-FM|springcleaning|Spring Cleaning}}
|Goldwell
|{{Forumlink|https://forums.thedarkmod.com/topic/17510-fan-mission-spring-cleaning-by-goldwell-20151030/}} [https://www.youtube.com/watch?v=JzPpmDK9Fxw Briefing]
|2015-10-30
|45
|No
|Yes
|Yes
|[[Fan_Mission_Contests#2015_Halloween_Speed-build_Contest|HSC 15]]
|Mansion/Estate
|Spiders, Undead
|-

|-
!align=left|{{TDM-FM|the_golden_skull|The Golden Skull}}
|Sotha
|{{Forumlink|https://forums.thedarkmod.com/topic/17497-fan-mission-the-golden-skull-by-sotha-20151024/}}
|2015-10-25
|7
|No
|Yes
|No
|[[Fan_Mission_Contests#2015_Halloween_Speed-build_Contest|HSC 15]]
|Mansion/Estate
|Undead
|-

|-
!align=left|{{TDM-FM|ahouseoflockedsecrets|A House of Locked Secrets}}
|Moonbo
|{{Forumlink|https://forums.thedarkmod.com/topic/17163-fan-mission-a-house-of-locked-secrets-by-gelo-moonbo-fleisher-20150528/}} [https://www.youtube.com/watch?v=f5NuTJEZ8VE Trailer]
|2015-05-29
|195
|No
|Yes
|Yes
|[[Fan_Mission_Series#Shadowcursed series|Shadowcursed]]
|Church/Cathedral <br> Mansion/Estate
|Horror themes, <br> Undead
|-

|-
!align=left|{{TDM-FM|u2_flock|Ulysses 2: Protecting the Flock}}
|Sotha
|{{Forumlink|https://forums.thedarkmod.com/topic/17162-fan-mission-ulysses-2-protecting-the-flock-by-sotha-20150528/}}
|2015-05-28
|102
|No
|Yes
|No
|[[Fan_Mission_Series#Ulysses series|Ulysses]]
|Church/Cathedral
|
|-

|-
!align=left|{{TDM-FM|talbot|Sir Talbot's Collateral}}<br>(v6 2024/01/29)
|Baal and Bikerdude
|{{Forumlink|https://forums.thedarkmod.com/topic/17093-fan-mission-sir-talbots-collateral-by-baal-bikerdude-15042015/}} [https://www.youtube.com/watch?v=e3rdZfq4Omc Trailer]
|2015-04-15
|60
|Yes
|Yes
|Yes
|[[Fan_Mission_Series#Sir Talbot series|Sir Talbot]]
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|vfat3|Vengeance for a Thief Part 3}}
|Sir Taffsalot
|{{Forumlink|https://forums.thedarkmod.com/topic/16953-the-complete-vengeance-for-a-thief-campaign/}}
|2015-02-16
|25
|No
|Yes
|No
|[[Fan_Mission_Series#Vengeance for a Thief series|VFAT]]
|Church/Cathedral
|
|-

|-
!align=left|{{TDM-FM|bathhouse|Lord Edgar's Bathhouse}}
|Goldwell
|{{Forumlink|1=https://forums.thedarkmod.com/topic/16828-fan-mission-lord-edgars-bathhouse-by-goldwell-27122014/}} [https://www.youtube.com/watch?v=vYSZY7VzFEo Briefing]
|2014-12-27
|71
|No
|Yes
|Yes
|Lord Edgar
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|quinn|Quinn Co.}}<br>(Made into a campaign, 2015/02/04)<br>{{TDM-FM|m_lbb|La Banque Bienveillante}} {{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/21488-fan-mission-quinn-co-part-1-la-banque-bienveillante-remake-by-airship-ballet}}<br>(Re-Release, 2022/06/24)
|Airship Ballet
|{{Forumlink|1=https://forums.thedarkmod.com/topic/16912-fan-mission-chase-mercantile-by-airship-ballet-20150204/}}
|2014-11-22
|111
|No
|Yes : Quinn<br><br>No : Part 1
|No
|Quinn Co.
|Bank Jobs
|
|-

|-
!align=left|{{TDM-FM|exhumed|Exhumed}}
|Airship Ballet and Kyyrma
|{{Forumlink|1=https://forums.thedarkmod.com/topic/16658-fan-mission-exhumed-by-kyyrma-and-airship-ballet-20141104/}}
|2014-11-04
|24
|No
|Yes
|No
|[[Fan_Mission_Contests#2014 Halloween Speed-build Contest|HSC 14]]
|Church/Cathedral <br> Horror
|Undead
|-

|-
!align=left|{{TDM-FM|briarwood|Briarwood Cathedral}}
|buck28
|{{Mirrorlink|https://www64.zippyshare.com/v/25705489/file.html}}{{Forumlink|1=https://forums.thedarkmod.com/topic/16644-briarwood-cathedral/}}
|2014-10-29
|7
|No
|Yes
|No
|[[Fan_Mission_Series#Master thief Corso series|Corso]] <br> [[Fan_Mission_Contests#2014 Halloween Speed-build Contest|HSC 14]] '''WINNER'''
|Church/Cathedral <br> Horror
|Undead
|-

|-
!align=left|{{TDM-FM|onesteptoofar|One Step Too Far}}<br>(v2.0 2023/06/18)
|Dragofer
|{{Mirrorlink|https://www.dropbox.com/s/sfxcap1gfdzf318/onesteptoofar.pk4}}{{Forumlink|1=https://forums.thedarkmod.com/topic/16457-fan-mission-one-step-too-far-by-dragofer-20140804/}}
|2014-08-04
|9
|No
|Yes
|Yes
|[[Fan_Mission_Series#Of Brambles and Thorns series|Of Brambles and Thorns]]
|Pirate <br> Ship
|
|-

|-
!align=left|{{TDM-FM|lockner|Lockner Manor}}
|buck28
|{{Mirrorlink|https://www76.zippyshare.com/v/44108372/file.html}}{{Forumlink|1=https://forums.thedarkmod.com/topic/16452-new-mission-lockner-manor/}}
|2014-08-02
|6
|No
|Yes
|No
|[[Fan_Mission_Series#Master thief Corso series|Corso]]
|Mansion/Estate <br> Inn/Tavern
|
|-

|-
!align=left|{{TDM-FM|ulysses_genesis|Ulysses: Genesis}}
|Sotha
|{{Mirrorlink|https://www4.zippyshare.com/v/67195436/file.html}}{{Forumlink|1=https://forums.thedarkmod.com/topic/16428-fan-mission-ulysses-genesis-by-sotha-20140724/}}
|2014-07-24
|98
|No
|Yes
|Yes
|[[Fan_Mission_Series#Ulysses series|Ulysses]]
|Mansion/Estate
|Horror theme?
|-

|-
!align=left|{{TDM-FM|penny2_1|Penny Dreadful 2: All the way up}}
|Melan and Bikerdude
|{{Mirrorlink|https://mega.co.nz/#!EwoXHZYZ!tE_sKon2h4AWtWPNt9QS3FQClwmXdimhfjIMPcpCQ34}}{{Forumlink|1=https://forums.thedarkmod.com/topic/16387-fan-mission-penny-dreadful-2-by-melan-and-bikerdude-2014078/}} [https://www.youtube.com/watch?v=WmPfCfbeWvg Trailer]
|2014-07-08
|102
|No
|Yes
|No
|[[Fan_Mission_Series#Penny Dreadful series|Penny Dreadful]]
|Thieves' Highway / Rooftop
|Spiders
|-

|-
!align=left|{{TDM-FM|poets|Poets and Peasants}}
|Digi
|{{Mirrorlink|https://drive.google.com/file/d/0B1HHvWAgbWGfTkI0SXFubXZucXM}}{{Forumlink|1=https://forums.thedarkmod.com/topic/16373-fan-mission-poets-peasants-by-digi-62914}}
|2014-06-29
|1
|No
|Yes
|No
|
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|follow|A Reputation to Uphold}}
|Springheel
|{{Mirrorlink|https://www.mindplaces.com/follow.pk4}}{{Forumlink|1=https://forums.thedarkmod.com/topic/16204-fan-mission-a-reputation-to-uphold-by-springheel/}}
|2014-04-18
|25.5
|No
|Yes
|No
|[[Fan_Mission_Series#Corbin series|Corbin]]
|City Missions
|
|-

|-
!align=left|{{TDM-FM|breakingout|Breaking Out the Fence}}
|Kyyrma
|{{Mirrorlink|https://dl.dropboxusercontent.com/u/17706561/breakingout.pk4}}{{Forumlink|1=https://forums.thedarkmod.com/topic/16091-fan-mission-breaking-out-the-fence-17032014-by-kyyrma/}}
|2014-03-17
|11.6
|No
|Yes
|No
|[[Fan_Mission_Series#In A Time of Need series|In A Time of Need]]
|City Missions <br> Jail/Prison
|
|-

|-
!align=left|{{TDM-FM|innbiz|Inn Business}}<br>(v.1.48, 2014/03/08)
|RJFerret
|{{Mirrorlink|https://drive.google.com/file/d/0B81T2ZXLPqhTYWVaODRiSExGeGc}} {{Forumlink|1=https://forums.thedarkmod.com/topic/16018-fan-mission-inn-business-by-rjferret-20140303/}}
|2014-03-03
|6
|No
|Yes
|No
|
|Inn/Tavern <br> City Streets
|
|-

|-
!align=left|{{TDM-FM|ws3_cleighmoor|William Steele 3: Cleighmoor}}
|grayman
|{{Forumlink|https://forums.thedarkmod.com/topic/16011-fan-mission-cleighmoor-by-grayman-201431/#entry338349/}}
|2014-03-01
|38
|No
|Yes
|Yes
|[[Fan_Mission_Series#William Steele series|William Steele]]
|Sewers <br> Jail/Prison
|
|-

|-
!align=left|{{TDM-FM|ws2_homeagain|William Steele 2: Home Again}}
|grayman
|{{Forumlink|https://forums.thedarkmod.com/topic/15919-fan-mission-home-again-by-grayman-2014212/page__fromsearch__1}}
|2014-02-12
|26
|No
|Yes
|Yes
|[[Fan_Mission_Series#William Steele series|William Steele]]
|Thieves' Highway / Rooftop
|
|-

|-
!align=left|{{TDM-FM|gatehouse1_3|The Gatehouse}}
|Bikerdude Goldchocobo
|{{Mirrorlink|https://www.southquarter.com/tdm/fms/gatehouse.pk4}} {{Forumlink|https://forums.thedarkmod.com/topic/15844-fan-mission-the-gatehouse-by-bikerdude-goldchocobo-20140114/}} [https://www.youtube.com/watch?v=kcIe2Ucojqw Briefing]
|2014-01-29
|100
|No
|Yes
|Yes
|Remake of Evilartist's Doom 3 mod
|Castle/Fortress
|Ghosts
|-

|-
!align=left|{{TDM-FM|windowopportunity|Window of Opportunity}}<br>(v.1.43, 2014/01/01)
|RJFerret
|{{Mirrorlink|https://drive.google.com/file/d/0B81T2ZXLPqhTWTMzQXZtMVFBSG8}} {{Forumlink|1=https://forums.thedarkmod.com/topic/15727-fan-mission-window-of-opportunity-by-rjferret-20140101/}}
|2014-01-01
|7
|No
|Yes
|No
|
|Outdoor/Caves
|Spiders (not in short mode)
|-

|-
!align=left|{{TDM-FM|timeofneed|In A Time Of Need}}
|kyyrma
| {{Mirrorlink|https://www.mediafire.com/download/a97or40t1xrybh3/timeofneed_v1.zip}} {{Forumlink|https://forums.thedarkmod.com/topic/15354-fan-mission-in-a-time-of-need-by-kyyrma-20131112/}}
|2013-11-12
|5.6
|No
|Yes
|No
|[[Fan_Mission_Series#In A Time of Need series|In A Time of Need]]
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|requiem|Requiem}}
|Moonbo
| {{Mirrorlink|https://www.mediafire.com/download/l6o3vvj9y78hu89/requiem.pk4}} {{Forumlink|https://forums.thedarkmod.com/topic/15101-fan-mission-requiem-by-gelo-moonbo-fleisher-2013106/}}
|2013-10-08
|107.3
|Yes
|Yes
|Yes
|[[Fan_Mission_Series#Shadowcursed series|Shadowcursed]]
|Lost Civilizations <br> Church/Cathedral
|Undead
|-

|-
!align=left|{{TDM-FM|vfat2|Vengeance for a Thief Part 2}}
|Sir Taffsalot
| {{Mirrorlink|https://dl.dropboxusercontent.com/u/17706561/vfat2.pk4}} {{Forumlink|https://forums.thedarkmod.com/topic/15051-fan-mission-vengeance-for-a-thief-part-2-by-sir-taffsalot-06092013/}}
|2013-09-06
|22
|No
|Yes
|No
|[[Fan_Mission_Series#Vengeance for a Thief series|VFAT]] <br> [[Fan_Mission_Contests#2013 Community Unusual Contest|CUC 13]]
|Museum Heists
|
|-

|-
!align=left|{{TDM-FM|lordsnlegacy|Lords and Legacy}}
|Kvorning
| {{Mirrorlink|https://dl.dropboxusercontent.com/u/17706561/lordsnlegacy.pk4}} {{Forumlink|https://forums.thedarkmod.com/topic/15016-fan-mission-lords-legacy-by-kvorning-20130830/}}
|2013-08-30
|45
|No
|Yes
|No
|
|Thieves' Highway / Rooftop
|
|-

|-
!align=left|{{TDM-FM|naog|Not An Ordinary Guest}}
|DeTeEff (Fieldmedic)
| {{Mirrorlink|https://dl.dropboxusercontent.com/u/17706561/naog.pk4}} {{Forumlink|https://forums.thedarkmod.com/topic/14965-fan-mission-not-an-ordinary-guest-by-fieldmedic-20130801/}}
|2013-08-01
|79.6
|No
|Yes
|No
|[[Fan_Mission_Contests#2013 Community Unusual Contest|CUC 13]]
|City Missions
|
|-

|-
!align=left|{{TDM-FM|penny1_1|Penny Dreadful: Grail of Regrets}}
|Melan
| {{Forumlink|https://forums.thedarkmod.com/topic/14952-fan-mission-penny-dreadful-by-melan-20130728/}}
|2013-07-27
|74
|No
|Yes
|No
|[[Fan_Mission_Series#Penny Dreadful series|Penny Dreadful]]
|Horror
|Spiders, Undead
|-

|-
!align=left|{{TDM-FM|solarescape1|Solar Escape 1}}
|Tr00pertj
| {{Forumlink|https://forums.thedarkmod.com/topic/14944-fan-mission-solar-escape-1/}}
|2013-07-22
|6
|No
|Yes
|No
|
|Mansion/Estate <br> Sewers
|Spiders, Undead
|-

|-
!align=left|{{TDM-FM|lich_queens_demise|The Lich Queen's Demise}}
|Sotha
|{{Mirrorlink|https://dl.dropboxusercontent.com/u/17706561/lich_queens_demise.pk4}} {{Forumlink|https://forums.thedarkmod.com/topic/14826-fan-mission-the-lich-queens-demise-by-sotha-20130520/unread/}}
|2013-05-20
|97.6
|No
|Yes
|No
|[[Fan_Mission_Series#Thomas Porter series|Thomas Porter]] <br> [[Fan_Mission_Contests#2013 Community Unusual Contest|CUC 13]] '''WINNER'''
|Horror
|Undead
|-

|-
!align=left|{{TDM-FM|oldhabits2|Old Habits Rebuild}}
|Obsttorte
|{{Mirrorlink|https://www.mediafire.com/download/u2gwucibh17c45a/oldhabits.pk4}} {{Forumlink|https://forums.thedarkmod.com/topic/14827-fan-mission-old-habits-rebuild-by-obsttorte-20052013/}}
|2013-05-20
|28.6
|No
|Yes
|No
|
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|builders_blocks|The Builder's Blocks}}
|Jesps
|{{Mirrorlink|https://dl.dropboxusercontent.com/u/17706561/builders_blocks.pk4}} {{Forumlink|https://forums.thedarkmod.com/topic/14592-unusual-gameplay-contest-fm-the-builders-blocks-by-jesps/}}
|2013-03-18
|2.85
|No
|Yes
|No
|[[Fan_Mission_Contests#2013 Community Unusual Contest|CUC 13]]
|Experimental
|
|-

|-
!align=left|{{TDM-FM|broads|The Builder Roads}}
|Obsttorte
|{{Forumlink|https://forums.thedarkmod.com/topic/14449-fan-mission-the-builder-roads-by-obsttorte-20130119/}}
|2013-01-19
|2.3
|No
|Yes
|No
|
|Church/Experimental
|-

|-
!align=left|{{TDM-FM|ws1_north|William Steele 1: In the North}}
|grayman
|{{Forumlink|https://forums.thedarkmod.com/topic/14214-fan-mission-in-the-north-by-grayman-20121020/}}
|2012-10-20
|39.8
|No
|Yes
|Yes
|[[Fan_Mission_Series#William Steele series|William Steele]]
|Mansion/Estate
|Undead
|-

|-
!align=left|{{TDM-FM|oldhabits1|Old Habits}}
|Obsttorte
|{{Mirrorlink|https://www.mediafire.com/download.php?andes2xnsonssfj}} {{Forumlink|https://forums.thedarkmod.com/topic/14206-fan-mission-old-habits-by-obsttorte-20121019/}}
|2012-10-19
|12.8
|No
|Yes
|No
|
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|deceptiveshadowsv1_2|Deceptive Shadows}}
|ShadowHide
|{{Mirrorlink|https://www.sendspace.com/file/jzr9s7}} {{Forumlink|https://forums.thedarkmod.com/topic/14103-fan-mission-deceptive-shadows-by-shadowhide-16sep12/}}
|2012-09-16
|22.4
|No
|Yes
|Yes
|
|Outdoor/Pagan
|Spiders, Undead
|-

|-
!align=left|{{TDM-FM|vfat1|Vengeance for a Thief: Part 1}}
|Sir Taffsalot
|{{Mirrorlink|https://dl.dropbox.com/u/17706561/VFAT1.pk4}} {{Forumlink|https://forums.thedarkmod.com/topic/14068-fan-mission-vengeance-for-a-thief-part-1-by-sir-taffsalot-06092012/}}
|2012-09-06
|20.9
|No
|Yes
|No
|[[Fan_Mission_Series#Vengeance for a Thief series|VFAT]]
|Jail/Prison
|
|-

|-
!align=left|{{TDM-FM|phrase_book|The Phrase Book}}
|Sotha
|{{Mirrorlink|https://dl.dropbox.com/u/17706561/phrase_book.pk4}} {{Forumlink|https://forums.thedarkmod.com/topic/13799-fan-mission-the-phrase-book-by-sotha-20120512/}}
|2012-05-11
|24
|No
|Yes
|No
|[[Fan_Mission_Series#Thomas Porter series|Thomas Porter]]
|Thieves' Highway / Rooftop
|
|-

|-
!align=left|{{TDM-FM|remembrance|In Remembrance of Him}}
|RPGista
|{{Mirrorlink|https://dl.dropbox.com/u/17706561/remembrance.pk4}} {{Forumlink|https://forums.thedarkmod.com/topic/13749-fan-mission-in-remembrance-of-him-by-rpgista/}}
|2012-04-22
|27.6
|No
|Yes
|No
|[[Fan_Mission_Contests#2012_Community_Beginner_Contest|CBC 12]]
|City Missions
|Undead
|-

|-
!align=left|{{TDM-FM|rightful|Rightful Property}}
|jysk
|{{Mirrorlink|https://dl.dropbox.com/u/17706561/rightful1.1b.pk4}} {{Forumlink|https://forums.thedarkmod.com/topic/13711-fan-mission-rightful-property-by-jysk-20120413/}}
|2012-04-12
|22.5
|No
|Yes
|No
|[[Fan_Mission_Contests#2012_Community_Beginner_Contest|CBC 12]]
|Bank Jobs
|Spiders
|-

|-
!align=left|{{TDM-FM|sneak_destroy|Sneak & Destroy}}<br>(v2 EFX, 2022/11/16)
|SeriousToni
|{{Mirrorlink|https://minus.com/mVcf61n3G/1f}} {{Forumlink|https://forums.thedarkmod.com/topic/13706-fan-mission-sneak-destroy-by-serioustoni-beginners-contest-2012/}}
|2012-04-11
|147
|Yes
|Yes
|Yes
|[[Fan_Mission_Contests#2012_Community_Beginner_Contest|CBC 12]] '''WINNER'''
|City Missions
|
|-

|-
!align=left|{{TDM-FM|houseoftheo|House of Theo}}
|Theothesnopp
|{{Mirrorlink|https://www.gamefront.com/files/21053391/houseoftheo__2__2.pk4}} {{Forumlink|https://forums.thedarkmod.com/topic/13242-fan-mission-house-of-theo/}}
|2011-12-04
|6.2
|No
|Yes
|No
|
|Castle/Fortress
|
|-

|-
!align=left|{{TDM-FM|crystalgrave2_1|Crystal Grave}} <br>(v.2.0, 2013/02/09)
|ERH+ Bikerdude
|{{Mirrorlink|https://dl.dropbox.com/u/17706561/crystalgravev2.pk4}} {{Forumlink|https://forums.thedarkmod.com/topic/14510-fan-mission-crystal-grave-v2-by-erh-and-bikerdude-20130209/unread/}}
|2011-11-15
|12.4
|No
|Yes
|No
|
|Horror
|Undead
|-

|-
!align=left|{{TDM-FM|claw1_31|Dragon's Claw}}<br>(v1.31, 2020/11/02)
|Bikerdude, Flanders (map assets)
|{{Mirrorlink|https://www.gamefront.com/files/20948800/claw.pk4}} {{Forumlink|https://forums.thedarkmod.com/topic/13181-fan-missiondragons-claw-by-b1k3rdude-31102011/}}
|2011-10-31
|98
|No
|Yes
|No
|[[Fan_Mission_Contests#2011_Halloween_Speed-build_Contest|HSC 11]]
|City Missions
|
|-

|-
!align=left|{{TDM-FM|antr|A Night to Remember}}<br>(v2.1, 2023/05/04)
|DeTeEff (Fieldmedic)
|New → {{Forumlink|https://forums.thedarkmod.com/topic/19452-a-night-to-remember/}} <br>Old → {{Forumlink|https://forums.thedarkmod.com/topic/13177-fan-mission-a-night-to-remember-by-fieldmedic-20111030/}}
|2011-10-31
|33
|No
|Yes
|No
|[[Fan_Mission_Contests#2011_Halloween_Speed-build_Contest|HSC 11]]
|Mansion/Estate <br> Horror
|Ghosts
|-

|-
!align=left|{{TDM-FM|thecreeps|The Creeps}}
|Mortem Desino
|{{Mirrorlink|https://www.gamefront.com/files/20939925/thecreeps.pk4}} {{Forumlink|https://forums.thedarkmod.com/topic/13176-fan-mission-creeps-the-20111030-by-mortem-desino/}}
|2011-10-30
|61
|No
|Yes
|No
|[[Fan_Mission_Contests#2011_Halloween_Speed-build_Contest|HSC 11]]
|Horror
|Ghosts
|-

|-
!align=left|{{TDM-FM|blackbog|House in Blackbog Hollow}}
|Stumpy
|{{Mirrorlink|https://www.bookofages.co.uk/doom3/mods/blackbog.html}} {{Forumlink|https://forums.thedarkmod.com/topic/13172-fan-mission-house-in-blackbog-hollow-by-stumpy-20111028/}}
|2011-10-28
|12
|No
|Yes
|No
|[[Fan_Mission_Contests#2011_Halloween_Speed-build_Contest|HSC 11]]
|Horror
|Spiders, Undead
|-

|-
!align=left|{{TDM-FM|lstl|Let Sleeping Thieves Lie}}
|Sir Taffsalot, Bikerdude
|{{Mirrorlink|https://www.mediafire.com/?zkd1jn4lpwgioh9}} {{Forumlink|https://forums.thedarkmod.com/index.php?/topic/13153-let-sleeping-thieves-lie-by-sir-taffsalot-bikerdude-20102011/}}
|2011-10-20
|13
|No
|Yes
|No
|
|Tombs, Catacombs & Crypts
|Undead
|-

|-
!align=left|{{TDM-FM|samhain|Samhain Night}}<br>(v3.3, 2020/03/02)
|PranQster
|{{Mirrorlink|https://jdchoate.mcn.org/games/darkmod/samhain.zip}} {{Forumlink|https://forums.thedarkmod.com/index.php?/topic/13127-fan-mission-samhain-night-on-bone-hill-by-pranqster-20111009/}}
|2011-10-09
|4.8
|Yes
|Yes
|No
|[[Fan_Mission_Contests#2011_Halloween_Speed-build_Contest|HSC 11]]
|Horror
|Spiders, Undead
|-

|-
!align=left|{{TDM-FM|score_to_settle|A Score to Settle}}
|Springheel
|{{Mirrorlink|https://www.mediafire.com/?f3o7hm4h4ew7o3l}} {{Forumlink|https://forums.thedarkmod.com/index.php?/topic/12894-fan-mission-%2348-a-score-to-settle-by-springheel-20110701/}}
|2011-07-01
|135
|No
|Yes
|No
|[[Fan_Mission_Series#Corbin series|Corbin]]
|City Missions
|
|-

|-
!align=left|{{TDM-FM|siegeshop|Siege Shop}}<br>(v5.0 2020/09/07)
|PranQster and Lowenz
|{{Mirrorlink|https://jdchoate.mcn.org/games/darkmod/siegeshop.pk4}} {{Forumlink|https://forums.thedarkmod.com/index.php?/topic/12874-fan-mission-the-siege-shop-by-pranqster-20110626/}} {{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20559-the-siege-shop-07092020/}}
|2011-06-26
|32.2
|Yes
|Yes
|No
|
|Castle/Fortress
|
|-

|-
!align=left|{{TDM-FM|alberic3|Alberic's Curse}}<br>( v3.11 EFX, 2024/02/23 )
|Bikerdude
|{{Mirrorlink|https://www.gamefront.com/files/20459738/alberic.pk4}} {{Forumlink|https://forums.thedarkmod.com/index.php?/topic/12850-fan-mission-alberics-curse-by-b1k3rdude-20062011/}}
|2011-06-20
|51.6
|Yes
|Yes
|No
|[[Fan_Mission_Contests#2011_Community Seasons Contest|CSC 11]] '''WINNER''' <br> T2 FM homage
|Church/Cathedral
|Spiders, Undead
|-

|-
!align=left|{{TDM-FM|reap|Reap As You Sow}}
|DeTeEff (Fieldmedic)
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/12849-fan-mission-reap-as-you-sow-by-fieldmedic-20110619/}}
|2011-06-19
|52
|No
|Yes
|No
|[[Fan_Mission_Contests#2011_Community Seasons Contest|CSC 11]]
|Outdoor/Daylight <br> Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|rake_off|Rake Off}}
|Jesps
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/12846-fm-rake-off-19-06-2011/}}
|2011-06-19
|8
|No
|Yes
|No
|[[Fan_Mission_Series#Selis Woderose series|Selis Woderose]] <br> [[Fan_Mission_Contests#2011_Community Seasons Contest|CSC 11]]
|Castle/Fortress
|
|-

|-
!align=left|{{TDM-FM|winterharvest|Winter Harvest}}<br>(v2.5 2024/12/15 with Bikerdude)
|ShadowHide
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/12690-seasons-contest-entry-winter-harvest-by-shadowhide/}} '''[https://forums.thedarkmod.com/index.php?/topic/12952-fm-winter-harvest-v2-by-bikerdude-and-shadowhide/ V2]'''
|2011-05-08
|20.2
|Yes
|Yes
|Yes
|[[Fan_Mission_Contests#2011_Community Seasons Contest|CSC 11]]
|Outdoor/Pagan
|Spiders
|-

|-
!align=left|{{TDM-FM|fauchard1_1|Fiasco at Fauchard Street}}
|Melan
|{{Mirrorlink|https://rapidshare.com/files/460141132/fauchard.pk4}} {{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/12655-fan-mission-fiasco-at-fauchard-street-by-melan-20110501//}}
|2011-05-01
|62
|No
|Yes
|No
|[[Fan_Mission_Series#Sir Talbot series|Sir Talbot]]
|Thieves' Highway / Rooftop
|
|-

|-
!align=left|{{TDM-FM|mandrasola|Mandrasola}}
|Sotha
|{{Mirrorlink|https://www.mediafire.com/?2ox2nbhh796ne71}} {{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/12575-fan-mission-mandrasola-by-sotha-20110410/}}
|2011-04-10
|10
|No
|Yes
|Yes
|[[Fan_Mission_Series#Thomas Porter series|Thomas Porter]] <br> [[Fan_Mission_Contests#2011_Community Seasons Contest|CSC 11]]
|City Missions
|Undead
|-

|-
!align=left| Q4 Conversion: Yan's Test
|Bikerdude
|{{Mirrorlink|https://www.moddb.com/mods/the-dark-mod/addons/yantdm1-1}} {{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/12506-fan-mission-q4-map-conversion-yantdm1-280311/}}
|2011-03-28
|28
|No
|No
|No
|
|
|
|-

|-
!align=left|{{TDM-FM|transaction|The Transaction}}
|Sotha
|{{Mirrorlink|https://www.mediafire.com/?ux7mx79wumnvcb6}} {{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/12408-fan-mission-the-transaction-by-sotha-20110304/}}
|2011-03-04
|10
|No
|Yes
|No
|[[Fan_Mission_Series#Thomas Porter series|Thomas Porter]]
|City Missions
|Horror Themes, Undead
|-

|-
!align=left|{{TDM-FM|lockdown1_2_1|Lockdown}}
|GameDevGoro Bikerdude Fidcal
|{{Mirrorlink|https://www.fidcal.com/darkuser/missions/lockdown1_2_1.pk4}} {{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/12064-fm-lockdown-part-1-by-gamedevgoro-and-bikerdude-20101224/}}
|2010-12-25
|3
|No
|Yes
|No
|Lockdown 1
|City Missions
|Undead
|-

|-
!align=left|{{TDM-FM|flakebridge|Flakebridge Monastery}}
|Jesps
|{{Mirrorlink|https://www.file-upload.net/download-3024426/flakebridge.pk4.html}} {{Mirrorlink|https://rapidshare.com/files/434997519/flakebridge.pk4}} {{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/11991-fm-flakebridge-monastery-by-jesps/}}
|2010-12-05
|16
|No
|Yes
|No
|[[Fan_Mission_Series#Selis Woderose series|Selis Woderose]]
|Church/Cathedral
|Undead
|-

|-
!align=left|{{TDM-FM|knighton_manor|Knighton Manor, The}}
|Sotha
|{{Mirrorlink|https://www.mediafire.com/?xrdts3j4t2qxre2}} {{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/11898-fan-mission-the-knighton-manor-by-sotha-20101109/page__view__getnewpost}}
|2010-11-09
|21
|No
|Yes
|No
|[[Fan_Mission_Series#Thomas Porter series|Thomas Porter]]
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|cathedral|St Albans Cathedral}}<br>(v2.0 2014/06/11)
|Bikerdude
|{{Mirrorlink|https://www.filefront.com/17464439/stac141.pk4}}{{Forumlink|1=https://forums.thedarkmod.com/topic/16343-fan-mission-st-albans-cathedral-v20-11062014/}} {{Loot|FM:TDM_St_Alban's_Cathedral_-_Bikerdude}}
|2010-11-01
|67
|No
|Yes
|No
|[[Fan_Mission_Series#St Alban series|St Alban]]
|Church/Cathedral
|Undead
|-

|-
!align=left|{{TDM-FM|swing1_2|Swing}}
|Komag
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/11660-vertigo-contest-entry-swing-by-komag-20100825/}} {{Loot|FM:TDM_Swing_-_Komag}}
|2010-08-25
|3
|No
|Yes
|No
|[[Fan_Mission_Contests#2010 Summer Vertical Contest|SVC 10]]
|Platforming/Jumping <br> Experimental
|
|-

|-
!align=left|{{TDM-FM|caduceus|The Caduceus of St. Alban}}<br>(v.1.5.5 2010/08/26)
|Bikerdude
|{{Mirrorlink|https://www.filefront.com/17237609/stalban.pk4/}}{{Forumlink|https://forums.thedarkmod.com/topic/11644-the-caduceus-of-st-alban-vertical-fm-contest-entry-aug-8th-2010/}}
|2010-08-23
|11.3
|No
|Yes
|No
|[[Fan_Mission_Series#St Alban series|St Alban]] <br> [[Fan_Mission_Contests#2010 Summer Vertical Contest|SVC 10]]
|Church/Cathedral
|Spiders
|-

|-
!align=left|{{TDM-FM|somewhere1_1|Somewhere Above the City}}<br>(v1.1 2010/08/27)
|grayman
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/11619-vertical-contest-mission-somewhere-above-the-city-by-grayman-aug-20-2010/}} {{Loot|FM:TDM_Somewhere_Above_the_City_-_grayman}}
|2010-08-20
|11
|No
|Yes
|Yes
|[[Fan_Mission_Contests#2010 Summer Vertical Contest|SVC 10]]
|Tombs, Catacombs & Crypts
|
|-

|-
!align=left|{{TDM-FM|betrayal|Betrayal}}<br>(v.1.1, 2010/09/01)
|DeTeEff (Fieldmedic)
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/11605-betrayal-by-fieldmedic-20100817-summer-fm-vertical-contest-entry/}} {{Loot|FM:TDM_Awaiting_the_Storm_-_HappyCheeze}}
|2010-08-17
|12
|No
|Yes
|No
|[[Fan_Mission_Contests#2010 Summer Vertical Contest|SVC 10]]
|Horror
|Undead
|-

|-
!align=left|{{TDM-FM|rift|Rift, The}}
|Baddcog
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/11599-vert-contest-mission-the-rift-by-baddcog-aug-15-2010/}}
|2010-08-15
|10
|No
|Yes
|No
|[[Fan_Mission_Contests#2010 Summer Vertical Contest|SVC 10]]
|Lost Civilizations
|Spiders, Undead
|-

|-
!align=left|{{TDM-FM|holetower|Illusionist's Tower}}
|stumpy
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/11541-illusionists-tower-by-stumpy-201085-summer-fm-vertical-contest-entry}} {{Forumlink|1=https://www.bookofages.co.uk/doom3/mods/holetower.html}} {{Loot|FM:TDM_Illusionist%27s_Tower_-_stumpy}}
|2010-08-05
|9
|No
|Yes
|No
|[[Fan_Mission_Contests#2010 Summer Vertical Contest|SVC 10]]
|Horror <br> Experimental
|Spiders, Undead
|-

|-
!align=left|{{TDM-FM|madmountain|Mad's Mountain}}
|Jesps
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/11510-fan-mission-mads-mountain-by-jesps-20100731}} {{Loot|FM:TDM_Lord_Dufford%27s_-_stumpy}}
|2010-07-31
|2
|No
|Yes
|No
|[[Fan_Mission_Contests#2010 Summer Vertical Contest|SVC 10]]
|Outdoor/Caves
|
|-

|-
!align=left|{{TDM-FM|glenham_tower|Glenham Tower, The}}
|Sotha
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/11423-fan-mission-the-glenham-tower-by-sotha-20100717}}
|2010-07-17
|5
|No
|Yes
|No
|[[Fan_Mission_Series#Thomas Porter series|Thomas Porter]] <br> [[Fan_Mission_Contests#2010 Summer Vertical Contest|SVC 10]] '''WINNER'''
|Castle/Fortress <br> Horror
|Undead
|-

|-
!align=left|{{TDM-FM|pandoras_box|Pandora's Box}}
|Jesps, Fidcal
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/11381-fan-mission-pandoras-box-by-jesps20100711}} {{Loot|FM:TDM_Pandora%27s_Box_-_Jesps}}
|2010-07-11
|7
|No
|Yes
|No
|
|Pirate <br> Ship <br> Experimental
|
|-

|-
!align=left|{{TDM-FM|beleaguered_fence|Beleaguered Fence, The}}
|Sotha
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/11298-fan-mission-the-beleaguered-fence-by-sotha-20100623}} {{Loot|FM:TDM_The_Beleaguered_Fence_-_Sotha}}
|2010-06-23
|11
|No
|Yes
|No
|[[Fan_Mission_Series#Thomas Porter series|Thomas Porter]]
|Jail/Prison
|
|-

|-
!align=left|{{TDM-FM|delivery|Special Delivery, A}}
|Silencium18
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/11247-fan-mission-a-special-delivery-by-silencium1820100612}} {{Loot|FM:TDM_A_Special_Delivery_-_Silencium18}}
|2010-06-12
|2
|No
|Yes
|No
|
|Warehouse
|
|-

|-
!align=left|{{TDM-FM|alchemist|Alchemist, The}}<br>(2010/06/04)
|Sotha, Fidcal
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/11170-fan-mission-the-alchemist-by-sotha-fidcal20100601}} {{Loot|FM:TDM_The_Alchemist_-_Sotha_%26_Fidcal}}
|2010-06-01
|27
|No
|Yes
|No
|[[Fan_Mission_Series#Thief's Den series|Thief's Den]]
|City Missions
|Undead
|-

|-
!align=left|{{TDM-FM|storm|Awaiting The Storm}}
|HappyCheeze
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/11095-fm-awaiting-the-storm-by-happycheeze-20200522}} {{Loot|FM:TDM_Awaiting_the_Storm_-_HappyCheeze}}
|2010-05-22
|4
|No
|Yes
|No
|
|City Missions
|
|-

|-
!align=left|{{TDM-FM|sound_alert_trainer|Sound Alert & Blackjack Trainer}}
|Dark Mod Team
|
|2010-05-14
|0.2
|No
|No
|No
|
|Training
|
|-

|-
!align=left|{{TDM-FM|nhat3|No Honor Among Thieves}}<br>(v.4.3 EFX, Subtitles, Water Effects 2024/02/23)
|Goldchocobo, RailGun, Mortem Desino, Bikerdude
|{{Mirrorlink|https://tinyurl.com/2a9mdcs}}{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/10993-fan-mission-no-honor-among-thieves-20100429}} {{Loot|FM:TDM_No_Honor_Among_Thieves_-_Goldchocobo}}
|2010-04-29
|229.8
|Yes
|Yes
|Yes
|
|Church/Cathedral; City Missions; Outdoor/Pagan, Mansion/Estate
|Spiders, Undead
|-

|-
!align=left|{{TDM-FM|heartv2|Heart of Lone Salvation, The}}<br>(v.2.0, 2014/04/12)
|Fidcal, Baddcog, Bikerdude
|{{Forumlink|1=https://forums.thedarkmod.com/topic/10878-fan-mission-the-heart-of-lone-salvation-by-fidcal-baddcog-bikerdude-20100402/?p=213506}} {{Walkthrough|FM:TDM_The_Heart_of_Lone_Salvation_-_Fidcal_%26_Baddcog_%26_Bikerdude}} {{loot|FM:TDM_The_Heart_of_Lone_Salvation_-_Fidcal_%26_Baddcog_%26_Bikerdude}}
|2010-04-02
|41
|No
|Yes
|No
|[[Fan_Mission_Series#Thief's Den series|Thief's Den]]
|City Missions
|Spiders
|-

|-
!align=left|{{TDM-FM|dufford|Lord Dufford's}}
|stumpy
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/10868-fan-mission-lord-duffords-20100331}} {{Loot|FM:TDM_Lord_Dufford%27s_-_stumpy}}
|2010-03-31
|22
|No
|Yes
|No
|
|City Missions
|
|-

|-
!align=left|{{TDM-FM|builders_influence|Builder's Influence, The}}<br>(2010/03/23)
|Railgun, Springheel
|{{Mirrorlink|https://www.fidcal.com/darkuser/missions/builders_influence.pk4}}{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/10811-fan-mission-the-builders-influence-20100320/}} {{Loot|FM:TDM_The_Builders_Influence_-_Railgun%26Springheel}}
|2010-03-20
|15
|No
|Yes
|No
|[[Fan_Mission_Series#Corbin series|Corbin]]
|Castle/Fortress
|
|-

|-
!align=left|{{TDM-FM|business3|Business as Usual}}<br>(v3.0 2013/01/19)
|Bikerdude
|{{Mirrorlink|1=https://rapidshare.com/files/335299431/business.pk4.html}}{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/10533-fan-mission-business-as-usual-by-b1k3rdude-14012010-christmas-fm-contest-entry/page__view__findpost__p__207055}}{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/14450-fan-mission-business-as-usual-v30-20130119/}}
|2010-01-14
|16.1
|No
|Yes
|No
|[[Fan_Mission_Contests#2009 Grand Christmas Contest|GCC 09]]
|Sewers
|
|-

|-
!align=left|{{TDM-FM|returntothecity|Return to the City}}<br>(v3.0 2015/01/03)
|Melan, Bikerdude
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/10509-fan-mission-return-to-the-city-by-melan-20100110/}} {{Forumlink|1=https://www.ttlg.com/forums/showthread.php?t=130519/}} {{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/12390-fan-mission-return-to-the-city-v2-01032011/}}
|2010-01-10
|26
|No
|Yes
|No
|[[Fan_Mission_Series#Sir Talbot series|Sir Talbot]] <br> [[Fan_Mission_Contests#2009 Grand Christmas Contest|GCC 09]] '''WINNER'''
|City Missions
|
|-

|-
!align=left|{{TDM-FM|sons_of_baltona_1|Sons of Baltona 1, The}}
|Carnage
|{{Mirrorlink|1=https://www.mediafire.com/?m4ywobjodm0}}{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/10498-fan-mission-the-sons-of-baltona-1-by-carnage-20100109}}
|2010-01-09
|3
|No
|Yes
|No
|[[Fan_Mission_Contests#2009 Grand Christmas Contest|GCC 09]] / Baltona 1
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|living_expenses|Living Expenses}}
|Sonosuke
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/10451-fm-living-expenses-by-sonosuke-2-jan-10/page__view__findpost__p__205386}}
|2010-01-02
|6
|No
|Yes
|No
|[[Fan_Mission_Contests#2009 Grand Christmas Contest|GCC 09]]
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|trapped|Trapped!}}
|RailGun
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/10442-fm-trapped-by-railgun-dec-30/page__view__findpost__p__205092}}
|2009-12-30
|6
|No
|Yes
|No
|
|Jail/Prison
|
|-

|-
!align=left|{{TDM-FM|parcel|Parcel, The}}
|Xonze
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/10404-fm-the-parcel-by-xonze-dec-24/page__view__findpost__p__204459}}
|2009-12-24
|7
|No
|Yes
|No
|[[Fan_Mission_Contests#2009 Grand Christmas Contest|GCC 09]]
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|too_late|Too Late}}
|Nielsen74
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/10400-fm-too-late-by-nielsen74-24-dec-09/page__view__findpost__p__204396}}
|2009-12-24
|4
|No
|Yes
|No
|[[Fan_Mission_Contests#2009 Grand Christmas Contest|GCC 09]]
|Warehouse
|
|-

|-
!align=left|{{TDM-FM|thieves|Thieves}}
|Silencium, RailGun, Fidcal
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/10286-fm-the-thieves-nov-2509/}}
|2009-11-26
|9
|No <br> [https://www.moddb.com/mods/the-dark-mod/addons/unofficial-thieves-efx Unofficial EFX Build]
|Yes
|No
|
|City Missions
|
|-

|-
!align=left|{{TDM-FM|patently_dangerous|Patently Dangerous}}<br>(v.2.0 EFX, 2021/01/03)
|demagogue
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/10125-fm-patently-dangerous-oct3109/page__view__findpost__p__199324/}}
|2009-10-31
|22.5
|Yes
|Yes
|No
|
|City Missions
|
|-

|-
!align=left|{{TDM-FM||Dark Mod Training Mission, The}}
|TDM Team
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/9932-fm-training-mission-17-oct-09/}}
|2009-10-17
|6
|Yes ( 2.13 beta )
|
|No
|[[Fan_Mission_Series#Introduction_campaign|Official Campaign]]
|Training <br> Platforming/Jumping
|
|-

|-
!align=left|{{TDM-FM|crown_of_penitence|Crown of Penitence, The}}
|Jesps
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/9934-fm-crown-of-penitence-by-jesps-17-oct-09/}}
|2009-10-16
|12
|No
|Yes
|No
|
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|chalice1_1|Chalice of Kings, The}}<br>(v.2.0, 2015/09/24) (Bikerdude and Xarg)
|Fidcal
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/9935-fm-chalice-of-kings-by-fidcal-17-oct-09/}} {{Loot|FM:TDM_Chalice_of_Kings_-_Fidcal}}
|2009-10-15
|3
|No
|Yes
|No
|[[Fan_Mission_Series#Thief's Den series|Thief's Den]]
|Castle/Fortress
|
|-

|-
!align=left|{{TDM-FM|outpost|Outpost, The}}
|angua, greebo
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/9937-fm-the-outpost-by-angua-greebo-17-oct-09/}}
|2008-12-23
|2
|No
|Yes
|No
|
|Castle/Fortress
|
|-

|-
!align=left|{{TDM-FM||Mission 2: Tears of Saint Lucia, The}}<br>(v.3.0, 2017/02/14)
|TDM Team
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/10579-fan-mission-the-tears-of-st-lucia-20081021/page__view__findpost__p__207972}} {{Loot|FM:TDM_The_Tears_of_Saint_Lucia_-_jdude}} [https://www.youtube.com/watch?v=yrGxoi3LSGg Briefing]
|2008-10-21
|20.3
|Yes (2.11)
|
|Yes
|[[Fan_Mission_Series#Introduction_campaign|Official Campaign]]
|Church/Cathedral
|Spiders
|-

|-
!align=left|{{TDM-FM|closemouthed_shadows|Closemouthed Shadows}}<br>(v.2.0, 2012/01/15)
|LordSavage, Bikerdude
|{{Forumlink|1=https://forums.thedarkmod.com/topic/13383-fan-mission-closemouthed-shadows-2008-reworked-for-tdm-107-20120115/}}
|2008-09-21
|2
|No
|Yes
|No
|Closemouthed Shadows 1
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|thiefsden|Thief's Den}}<br>(v.2.0, 2010/07/04)
|Fidcal, greebo
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/11347-fan-mission-thiefs-den-re-release-by-fidcal20100704}} {{Walkthrough|FM:TDM_Thief's_Den_-_Fidcal}} {{Loot|FM:TDM_Thief%27s_Den_-_Fidcal}}
|2008-01-18
|3
|No
|Yes
|No
|[[Fan_Mission_Series#Thief's Den series|Thief's Den]]
|City Missions
|
|}

To see a speculative list of Upcoming Fan Missions, please visit: [[Upcoming Fan Missions]]

== Table notes ==

'''Links Key'''
{|class="wikitable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2
|-
|[https://wiki.thedarkmod.com/images/b/be/Icon_forum.png https://wiki.thedarkmod.com/images/b/be/Icon_forum.png]
|Link to discussion in Forums
|-
|{{Mirrorlink|}}
|Misc. download mirror
|-
|{{Loot|}}
|Loot list
|-
|{{Walkthrough|}}
|Walkthrough
|}

----

'''Mission Type Key'''

''Bear in mind that individual FMs can have combinations of two or three of these overarching genres/themes, rather than just a single one.''

{|class="wikitable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2
|-
|'''''Bank Jobs'''''
|Fan mission involving a heist or other thievy action inside a local banking institution. Will often contain the outsmarting of security systems, gaining access to a safe and cracking its code.
|-
|'''''Castle/Fortress'''''
|Fan mission involving a heist or other thievy action inside or outside a castle or fortress, either one that serves as a military garrison, or as someone's private residence. Frequently involves background characters from the nobility.
|-
|'''''City Missions'''''
|Fan mission that is set mainly in the streets and public spaces of an urban area, such as a town or city. Though the player is most often out on the streets, these missions tend to also involve some degree of exploration and infiltration into private and public buildings alike.
|-
|'''''Church/Cathedral'''''
|Fan mission set in and around religious buildings and institutions, such as churches, monasteries, cathedrals, church bureaus, church workshops, etc. Frequently involves [[Clergy/Builder_Characters|ecclesiastical characters]] from the TDM setting's [[Builders|Builder Church]].
|-
|'''''Experimental'''''
|Fan mission which involves some creative design or gameplay element that isn't typical for the vast majority of TDM missions. FMs set in highly unusual environments, or with a puzzle-like nature, can fit under this label.
|-
|'''''Inn/Tavern'''''
|Fan mission set mostly in and around an inn, tavern or shanty. Usually focused on robbing some rich guest, acquiring an item stored by the guest at the inn, or gathering intel at the inn.
|-
|'''''Jail/Prison'''''
|Fan mission involving an escape from a prison (by the imprisoned player character), infiltration of a prison to gather intel from inmates or help an inmate escape the prison, etc.
|-
|'''''Lost Civilizations'''''
|Fan mission focused on the exploration of ancient ruins, whether above ground or in deep subterranean caverns. Can often overlap with the ''Horror'' or ''Tombs, Catacombs & Crypts'' type of mission, but not necessarily.
|-
|'''''Horror'''''
|Fan mission with an overt horror theme. Depending on the author's approach and intentions, it can focus on psychological horror, or horror based on danger from supernatural threats, or varying combinations of both.
|-
|'''''Mansion/Estate'''''
|Fan mission involving a heist or other thievy action inside someone's private residence (a fancy house, a manor house) and its surrounding grounds. Frequently involves background characters from the nobility or the more affluent townsmen or citizens.
|-
|'''''Museum Heists'''''
|Fan mission focusing on a heist in a museum, art gallery or other institution storing priceless artefacts, artworks, gemstone collections, etc.
|-
|'''''Outdoor/Forest'''''
|Fan mission set in a mostly natural outdoor environment, involving the exploration of forested areas and woodland. Can overlap with other Outdoor style missions.
|-
|'''''Outdoor/Caves'''''
|Fan mission set in a mostly natural outdoor environment, but involving the exploration of natural caves and caverns. Can overlap with other Outdoor style missions.
|-
|'''''Outdoor/Daylight'''''
|Fan mission set in a mostly outdoor environment, during the daytime (in contrast to the usual TDM missions, set at night time or early dusk). Can overlap with other Outdoor style missions.
|-
|'''''Outdoor/Pagan'''''
|Fan mission set in a mostly natural outdoor environment, involving some presence of [[Pagans|pagan tribes]] from TDM's setting. Perhaps even pagan camps and settlements. Can overlap with other Outdoor style missions.
|-
|'''''Pirate'''''
|Fan mission involving the presence of characters engaging in piracy or smuggling, and various related piratical themes. Can overlap with the ''Ship'' type of mission, but not necessarily.
|-
|'''''Platforming/Jumping'''''
|Fan mission focusing on testing the player's movement, jumping and climbing skills, with or without equipment.
|-
|'''''Sewers'''''
|Fan mission which involves the use of the city sewers or others sewers in some way, often as a stealthy means of entry or escape.
|-
|'''''Ship'''''
|Fan mission which takes place aboard a vessel, in port or at sea, or otherwise involves ships to a great degree. Can overlap with the ''Pirate'' type of mission, but not necessarily.
|-
|'''''Thieves' Highway / Rooftop'''''
|Fan mission involving a lot of movement and travel on the rooftops of a town or city (colloquially "The Thieves' Highway").
|-
|'''''Tombs, Catacombs & Crypts'''''
|Fan mission involving the exploration of old tombs, catacombs and crypts, often for the purposes of treasure and artefact hunting. Can often overlap with the ''Horror'' or ''Lost Civilizations'' type of mission, but not necessarily.
|-
|'''''Train'''''
|Fan mission which takes place aboard a train, either one already underway or one waiting at a station. Given TDM's setting, most likely a train with an early steam locomotive.
|-
|'''''Training'''''
|Fan mission label that is unique to the official Training Mission, an open-ended tutorial mission where players can practice and test their TDM gameplay skills at their own leisure, and to the smaller blackjacking-trainer FM, which focuses on practicing NPC knockouts by the player.
|-
|'''''Warehouse'''''
|Fan mission which takes place in and around a warehouse, usually in some industrial area of a city, or at a port.
|}

----

'''Contest Key'''

GCC 09: [[Fan_Mission_Contests#2009 Grand Christmas Contest|Grand Christmas Contest 2009]]

SVC 10: [[Fan_Mission_Contests#2010 Summer Vertical Contest|Summer Vertical Contest 2010]]

CSC 11: [[Fan_Mission_Contests#2011 Community Seasons Contest|Community Seasons Contest 2011]]

HSC 11: [[Fan_Mission_Contests#2011 Halloween Speed-build Contest|Halloween Speed-Build Contest 2011]]

CBC 12: [[Fan_Mission_Contests#2012 Community Beginner Contest|Community Beginner Contest 2012]]

CUC 13: [[Fan_Mission_Contests#2013 Community Unusual Contest|Community Unusual Contest 2013]]

HSC 14: [[Fan_Mission_Contests#2014 Halloween Speed-build Contest|Halloween Speed-Build Contest 2014]]

HSC 15: [[Fan_Mission_Contests#2015 Halloween Speed-build Contest|Halloween Speed-Build Contest 2015]]

CCC 22: [[Fan_Mission_Contests#2022_Christmas_Connection_Contest|Christmas Connections Contest 2022]]

15YR: [[Fan_Mission_Contests#2024_15th_Anniversary_Contest|15th Anniversary Contest (2024)]]

----

== Editing this table ==
* Please only include playable missions that are fully released, not those currently in development or testing. Tutorials, demos, prefabs, etc. should be listed elsewhere.
* A mission title may be listed in plain text as a record of release, or preferably a link to an information page or primary direct download.
* List by release date descending (newest at the top).
* If a fan mission only has a single mirror/host please consider adding additional mirrors.

== See also ==
* [https://wiki.thedarkmod.com/index.php?title=Category:Official_FMs Fan missions] - An index of fan mission pages on this wiki.
* [https://wiki.thedarkmod.com/index.php?title=Category:Official_missions_(OMs) Official missions] - An index of Oficial mission pages on this wiki.
* [[Fan Mission Series]] - An overview of all currently known series or campaigns of fan missions interconnected by their stories or characters. There are already plenty in TDM, and have been since its early days as an expandable game.
* [[Mission recommendation discussions]] - An overview of past discussions on what FMs the community recommends to players looking for various challenges (difficulty, size, theme, setting, objectives, etc.).
* [[Fan Mission Contests]] - An overview of past and present contests in Fan Mission creation, by members of the TDM community.
* [[Upcoming Fan Missions]] - An overview of Fan Missions in development or tentatively planned. (''Do not'' edit the overview.)
* [https://tdmdb.com/missions tdmdb.com] An external TDM mission database, which data is partly coming from this wiki page.

{{general|sort=Fan Missions}}
[[Category:Fan Missions]]
[[Category:Official FMs| ]]

Fan Missions for The Dark Mod

2025-06-26T21:24:01Z

Frost Salamander: /* Missions table */

__NOTOC__
{{infobox|<center><br>'''Big Ugly Disclaimer:'''</center><br> '''The Dark Mod''' team does not necessarily support or endorse content listed here, and only hosts missions listed on the '''[https://www.thedarkmod.com/ official TDM website]'''. This is a community maintained list, and an ongoing work in progress. Most of the mirror links in this list are dead or are for missions that are not 2.0 compliant. Mission entries which are suspected to violate copyright must be text-only, and cannot contain links. Report and/or remove links found in violation of this rule.}}

* For details about editing this table, see [[#Editing_this_table|below]].
* For details about how to install Fan Missions please visit: [[Installing and Running Fan Missions]]
* To sort by a different criterion, click the [[Image:Sort none.gif]] icon in the relevant column header.

== Missions table ==
{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="19%"|Fan Mission Title
!bgcolor=#d0d0e0 width="14%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Links
!bgcolor=#d0d0e0 width="5%"|First Release
!bgcolor=#d0d0e0 width="2%"|Size (MB)
!bgcolor=#d0d0e0 width="2%"|EFX Reverb
!bgcolor=#d0d0e0 width="3%"|Translation Pack
!bgcolor=#d0d0e0 width="2%"|Sub - Titles
!bgcolor=#d0d0e0 width="10%"|Series
!bgcolor=#d0d0e0 width="16%"|Mission Type
!bgcolor=#d0d0e0 width="6%"|Spiders and Undead
|-



|-
!align=left|{{TDM-FM|crookshank|The Last Night on Crookshank Lane}}
|Jnon
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22947-fan-mission-the-last-night-on-crookshank-lane/}}
|2025-06-19
|77
|No
|No
|Yes
|
|City Missions, Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|lt4|The Lieutenant 4: A Reciprocal Gambit}}
|Frost_Salamander
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22945-fan-mission-the-lieutenant-4-a-reciprocal-gambit-by-frost_salamander/}}
|2025-06-18
|62
|Yes
|No
|No
|[[Fan_Mission_Series#The_Lieutenant_series|The Lieutenant]]
|City Missions, Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|footloose|Footloose museum theft}}
|Goblin of Akenash
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22654-fan-mission-footloose-museum-theft}}
|2025-02-05
|1.2
|No
|No
|No
|
|Museum Heist
|
|-

|-
!align=left|{{TDM-FM|scrooge|A Winter's Tale}} <br>(v1.4, 2025/01/13)
|Bikerdude
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22609-fan-mission-a-winters-tale-by-bikerdude-2024-11-30/}}
|2024-11-30
|140
|Yes
|No
|No
|[https://www.ttlg.com/forums/showthread.php?t=152747 TTLG Speed Jam]
|City Missions, Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|lastoffering|The Last Offering}}
|Sotha
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22594-fan-mission-the-last-offering-2024-11-16/}}
|2024-11-16
|2.7
|Yes
|No
|No
|
|Tombs, Catacombs & Crypts
|Horror Themes
|-

|-
!align=left|{{TDM-FM|gem_of_souls|Gem of Souls}}
|MirceaKitsune
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22583-fan-mission-gem-of-souls-31-10-2024/}}
|2024-10-31
|10
|Yes
|No
|No
|
|Church/Cathedral
|Undead, Horror Themes
|-

|-
!align=left|{{TDM-FM|pinnacle|Pinnacle: A Test of Talents}} <br>(v2.0, 2024/10/24)
|UncertainTitle, TwilitWitch
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22569-fan-mission-pinnacle-a-test-of-talents-hbd-tdm-15th-anniversary-contest/}}
|2024-10-17
|5
|No
|No
|No
|[[Fan_Mission_Contests#2024_15th_Anniversary_Contest|15YR]] Contest
|City Missions, Experimental
|
|-

|-
!align=left|{{TDM-FM|gemcutter|Volta 3: Gemcutter}}
|Kingsal
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22566-fan-mission-volta-iii-gemcutter-15th-anniversary-contest}}
|2024-10-16
|852
|Yes
|No
|Yes
|[[Fan_Mission_Contests#2024_15th_Anniversary_Contest|15YR]] '''WINNER'''<br> [[Fan_Mission_Series#Volta series|Volta]]
|Ship, City Missions, Moorish Architecture
|
|-

|-
!align=left|{{TDM-FM|yoft|You Only Fly Thrice}}
|DeTeEff
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22565-fan-mission-you-only-fly-thrice-by-deteeff-20241016/}}
|2024-10-16
|45
|Yes
|No
|Yes
|[[Fan_Mission_Contests#2024_15th_Anniversary_Contest|15YR]] Contest
|Ship <br> Experimental
|
|-

|-
!align=left|{{TDM-FM|wizt|The Wizard's Treasure}}
|thebigh
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22558-fan-mission-the-wizards-treasure-15th-anniversary-contest/}}
|2024-10-13
|7
|Yes
|No
|No
|[[Fan_Mission_Contests#2024_15th_Anniversary_Contest|15YR]] Contest
|Castle/Fortress
|
|-

|-
!align=left|{{TDM-FM|imperial_sword|The Imperial Sword}} <br>(v1.3.6, 2024/10/11)
|Bikerdude
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22541-fan-mission-the-imperial-sword-15yr-anniversary-contest/}}
|2024-09-21
|419
|Yes
|No
|Yes
|[[Fan_Mission_Contests#2024_15th_Anniversary_Contest|15YR]] Contest
|City Missions, Mansion/Estate
|Spiders
|-

|-
!align=left|{{TDM-FM|hhbam|Hidden Hands: Blood & Metal}} <br>(v4.0, 2024/11/29)
|JackFarmer
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22532-hidden-hands-blood-metal-campaign-01092024/}}
|2024-09-02
|1200
|Yes
|No
|Yes
|Hidden Hands 5
|
|Spiders, Undead, Horror Themes
|-

|-
!align=left|{{TDM-FM|faffairs|The Lieutenant 3: Foreign Affairs}} <br>(v4.0, 2024/11/08)
|Frost_Salamander
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22452-fan-mission-the-lieutenant-3-foreign-affairs-by-frost_salamander/}}
|2024-05-19
|501
|Yes
|No
|No
|The Lieutenant
|City Missions, Moorish Architecture
|
|-

|-
!align=left|{{TDM-FM|lookwhosmoving|Moving Day 2: Look Who's Moving Now}}
|wellingtoncrab
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22416-sad-news-%F0%9F%98%A2-but-fm-release/}}
|2024-04-01
|337
|No
|No
|No
|April Fools, <br>PTB (unofficial)
|Mansion/Estate, City Missions
|Humor
|-

|-
!align=left|{{TDM-FM|sneakandsouffle|Sneak & Soufflé}}
|Goldwell
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22417-fm-release-sneak-and-souffl%C3%A9-april-fools-mission-01042024/}}
|2024-04-01
|95
|Yes
|No
|No
|April Fools
|Mansion/Estate
|Humor
|-

|-
!align=left|{{TDM-FM|moongate|Moongate Ruckus}}
|Kingsal
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22419-having-trouble-sleeping-is-the-%F0%9F%8C%95moon-too-bright-the-%F0%9F%8E%BBmusic-too-loud-ive-got-an-fm-for-you/}}
|2024-04-01
|218
|Yes
|No
|No
|April Fools
|City Missions
|Humor
|-

|-
!align=left|{{TDM-FM|prize|Eye on the Prize}}
|Amadeus
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22418-fan-mission-eye-on-the-prize-412024/}}
|2024-04-01
|278
|No
|No
|Yes
|April Fools
|City Missions
|Humor
|-

|-
!align=left|{{TDM-FM|oldman|The Terrible Old Man}} <br>(v2.0, 2024/12/30)
|Ansome
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22393-fan-mission-the-terrible-old-man/}}
|2024-03-10
|11.7
|Yes
|No
|Yes
|
|Mansion/Estate, City Missions
|Horror Themes
|-

|-
!align=left|{{TDM-FM|sk_cooks|By The Cookbook}}<br>(v4.0 2024/07/08)
|Skaruts
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22357-fan-mission-by-the-cookbook/}}
|2024-02-02
|8.4
|No
|No
|No
|
|City Missions
|
|-

|-
!align=left|{{TDM-FM|altham|A Night in Altham}}
|joebarnin
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22296-fan-mission-a-night-in-altham/}}
|2023-12-05
|441
|Yes
|No
|Yes
|
|City Missions <br> Outdoor/Forest
|Spiders, Undead
|-

|-
!align=left|{{TDM-FM|spiderfinch|The Spider And The Finch}}<br>(v1.5.0 2024/07/11)
|GrodenVR
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22275-fan-mission-the-spider-and-the-finch-by-grodenglaive/}}
|2023-11-18
|45
|Yes
|No
|Yes
|
|Mansion/Estate <br> Outdoor/Forest
|Spiders
|-

|-
!align=left|{{TDM-FM|threepenny|The Threepenny Revue}}
|Jnon
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22229-fan-mission-the-threepenny-revue/}}
|2023-10-01
|21
|No
|No
|No
|
|City Missions
|
|-

|-
!align=left|{{TDM-FM|delisle|The House of deLisle}}
|thebigh
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22227-fan-mission-the-house-of-delisle/}}
|2023-10-01
|38
|Yes
|No
|No
|Duncan Lynch
|Mansion/Estate, City Missions
|Spiders, Undead, Body Horror
|-

|-
!align=left|{{TDM-FM|bridge2far|A Bridge Too Far}}
|cugzkani
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/22220-fan-mission-a-bridge-too-far/}}
|2023-09-22
|6
|No
|No
|No
|
|City Missions
|
|-

|-
!align=left|{{TDM-FM|highex|The Lieutenant 2: High Expectations}}
|Frost_Salamander
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21837-fan-mission-the-lieutenant-2-high-expectations-by-frost_salamander-20230424}}
|2023-04-24
|34.9
|Yes
|No
|No
|The Lieutenant
|Mansion/Estate, City Missions
|
|-

|-
!align=left|{{TDM-FM|seeking|Seeking Lady Leicester}}
|Grayman, Bikerdude, Amadeus, Dragofer, WellingtonCrab
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21799-fan-mission-seeking-lady-leicester-by-grayman-3212023/}}
|2023-03-22
|493
|Yes
|No
|Yes
|
|Mansion/Estate, City Missions
|Undead, Horror Themes
|-

|-
!align=left|{{TDM-FM|inplainsight|The Lieutenant 1: In Plain Sight}}
|Frost_Salamander
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21549-fan-mission-in-plain-sight-by-frost_salamander-20220807}}
|2022-08-07
|14
|Yes
|No
|No
|The Lieutenant
|City Missions
|Undead, Horror Themes
|-

|-
!align=left|{{TDM-FM|at1_lucy|The Adventures of Thomas: Lucy's Quest}}
|gg
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21453-the-adventures-of-thomas-lucys-quest-2022-06-08}}
|2022-06-08
|484
|Yes
|No
|No
|Thomas 1
|City Missions
|Spiders, Undead, Horror Themes
|-

|-
!align=left|{{TDM-FM|wwtw|Who Watches the Watcher?}}
|DeTeEff (Fieldmedic)
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21434-fan-mission-who-watches-the-watcher-v10-by-deteeff-20220528}}
|2022-05-28
|86
|Yes
|No
|Yes
|
|City Missions
|Horror Themes
|-

|-
!align=left|{{TDM-FM|sw1_ebound|Sam Wilson 1: Eastbound}}
|jonri
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21402-fan-mission-sam-wilson-1-eastbound-2022-05-07}}
|2022-05-07
|18
|Yes
|No
|No
|Sam Wilson
|Train
|
|-

|-
!align=left|{{TDM-FM|byanyothername|By Any Other Name}}<br>(v3 2024/06/05)
|joebarnin
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21331-fan-mission-by-any-other-name-by-joebarnin-2022310/}}
|2022-03-10
|124
|Yes
|No
|Yes
|
|Mansion/Estate, City Missions
|
|-

|-
!align=left|{{TDM-FM|housecall|A House Call}}
|thebigh
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21329-a-house-call-by-thebigh-mar-10-2022/}}
|2022-03-10
|10
|Yes
|No
|No
|Duncan Lynch
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|nobleaffairs|Noble Affairs}}
|Goldwell
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21318-fan-mission-noble-affairs-by-goldwell-20220222-tdm-210-required/}}
|2022-02-22
|488
|Yes
|No
|No
|
|City Missions
|Horror Themes
|-

|-
!align=left|{{TDM-FM|iris|Iris}} <br>(v1.3, 2024/05/26)
|Wellingtoncrab
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21289-fan-mission-iris-by-wellingtoncrab-tdm-210-required-20220213/}}
|2022-02-13
|549
|Yes
|No
|No
|[[Fan_Mission_Contests#2022_Christmas_Connection_Contest|CCC 22]] - '''WINNER'''
|City Missions
|Horror Themes
|-

|-
!align=left|{{TDM-FM|ptb0|PtB 0: Moving Day}}
|Jedi_Wannabe
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21283-fan-mission-paying-the-bills-0-moving-day-tdm-210-beta-only-202228/}}
|2022-02-08
|160
|Yes
|No
|No
|[[Fan_Mission_Contests#2022_Christmas_Connection_Contest|CCC 22]], PTB
|Mansion/Estate <br> Outdoor/Forest
|Spiders
|-

|-
!align=left|{{TDM-FM|written|Written in Stone}}
|Bikerdude, Amadeus, Dragofer
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21265-written-in-stone-beta-210-only-20220128/}}
|2022-01-28
|338
|Yes
|No
|Yes
|[[Fan_Mission_Contests#2022_Christmas_Connection_Contest|CCC 22]], Elixir
|City Missions
|Undead, Horror Themes
|-

|-
!align=left|{{TDM-FM|hazard|Hazard Pay}}
|Kingsal
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21264-fan-mission-hazard-pay-by-kingsal-tdm-beta-210-only/}}
|2022-01-28
|404
|Yes
|No
|Yes
|[[Fan_Mission_Contests#2022_Christmas_Connection_Contest|CCC 22]]
|Tombs, Catacombs & Crypts
|Undead
|-

|-
!align=left|{{TDM-FM|newford|Down and Out on Newford Road}}
|thebigh
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21260-down-and-out-on-newford-road-by-thebigh-jan-26-2022-christmas-connections-contest-entry/}}
|2022-01-26
|17
|Yes
|No
|No
|[[Fan_Mission_Contests#2022_Christmas_Connection_Contest|CCC 22]]
|Church/Cathedral, City Missions
|Undead, Horror Themes
|-

|-
!align=left|{{TDM-FM|deadeye|Deadeye}}
|Sotha
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21225-fan-mission-deadeye-by-sotha-20211231/}}
|2021-12-31
|1.8
|Yes
|No
|No
|
|City Missions
|
|-

|-
!align=left|{{TDM-FM|black_mage|The Black Mage}}
|Grayman, JackFarmer
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21215-the-black-mage/}}
|2021-12-23
|410
|Yes
|No
|Yes
|
|Castle/Fortress <br><br>In memoriam of Grayman {{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20933-we-have-lost-a-member-of-the-tdm-development-team/}}
|Horror Themes
|-

|-
!align=left|{{TDM-FM|ch1_eaton|Cole Hurst 1: Eaton}}
|bwyan
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21170-fan-mission-cole-hurst-1-eaton-by-bwyan-20211202/}}
|2021-12-01
|41
|Yes
|No
|No
|Cole Hurst
|Mansion/Estate, City Missions
|
|-

|-
!align=left|{{TDM-FM|cos0_thief|Chronicles of Skulduggery 0: To Catch a Thief}}
|Bienie
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21156-fan-mission-chronicles-of-skulduggery-0-to-catch-a-thief-20211120/}}
|2021-11-20
|15
|Yes
|No
|No
|[[Fan_Mission_Series#Chronicles_of_Skulduggery_series|Chronicles of Skulduggery]]
|City Missions, Mansion/Estate
|Horror Themes
|-

|-
!align=left|{{TDM-FM|away0|Away 0 - Stolen Heart}}
|Geep,_Atti_
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20964-away-0-stolen-heart-by-geep-_atti_-20210924/}}
|2021-11-12
|189.5
|No
|No
|No
|[[Fan_Mission_Series#Away_series|Away]]
|Inn/Tavern, Jail/Prison, <br> Museum Heist, Bank Job
|
|-

|-
!align=left|{{TDM-FM|hhta|Hidden Hands: Anomaly}}
|JackFarmer
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20909-hidden-hands-the-anomaly}}
|2021-05-01
|532.7
|Yes
|No
|No
|[[Fan_Mission_Series#Hidden_Hands_series|Hidden Hands]]
|Castle/Fortress <br> Outdoor/Forest
|Undead, Spiders
|-

|-
!align=left|{{TDM-FM|hareinthesnare|The Hare in the Snare: Part 1}}
|Frost_Salamander,Kerry000
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20883-fan-mission-the-hare-in-the-snare-part-1}}
|2021-04-09
|102.3
|Yes
|No
|Yes
|Hare in the Snare 1
|City Missions <br> Inn/Tavern
|
|-

|-
!align=left|{{TDM-FM|blackgrove|Blackgrove Manor}}<br>(v1.02, 2021/04/24)
|ddaazzaa
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20844-fan-mission-blackgrove-manor-by-ddaazzaa-20210314/}}
|2021-03-14
|24.7
|Yes
|No
|No
|
|Mansion/Estate
|Undead, Horror Themes
|-

|-
!align=left|{{TDM-FM|scroll|Scroll of Remembrance}}
|MirceaKitsune
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20613-fan-mission-scroll-of-remembrance-by-mirceakitsune-03112020/}}
|2020-11-03
|16.2
|Yes
|No
|No
|
|Mansion/Estate
|Undead, Horror Themes
|-

|-
!align=left|{{TDM-FM|factoryheist|The Factory Heist}}
|thebigh
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20562-the-factory-heist-12-sep-2020/}}
|2020-09-12
|1.1
|No
|No
|No
|Duncan Lynch
|Warehouse
|
|-

|-
!align=left|{{TDM-FM|nowandthen|Now and Then}}<br>(v3.0. 2025/03/19)
|joebarnin
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20560-fan-mission-now-and-then-by-joebarnin-20200908/}}
|2020-09-08
|236.1
|Yes
|No
|Yes
|
|Museum Heists
|
|-

|-
!align=left|{{TDM-FM|hhtlc|Hidden Hands: The Lost Citadel}}
|JackFarmer
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20490-hidden-hands-the-lost-citadel-23072020}}
|2020-07-23
|444
|Yes
|No
|No
|[[Fan_Mission_Series#Hidden_Hands_series|Hidden Hands]]
|Castle/Fortress
|Undead
|-

|-
!align=left|{{TDM-FM|cos3_sacricide|Chronicles of Skulduggery 3: Sacricide}}
|Bienie
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20483-fan-mission-chronicles-of-skulduggery-3-sacricide-20200718/}}
|2020-07-18
|97.8
|Yes
|No
|No
|[[Fan_Mission_Series#Chronicles_of_Skulduggery_series|Chronicles of Skulduggery]]
|City Missions
|Undead
|-

|-
!align=left|{{TDM-FM|painterswife|The Painter's Wife}}<br>(v1.4, 2025/06/10)
|Fractured Glass Company
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20436-fan-mission-the-painter’s-wife-by-fractured-glass-company-20200701/}}
|2020-07-01
|205
|Yes
|No
|Yes
|
|City Missions
|Spiders, Undead
|-

|-
!align=left|{{TDM-FM|anol|A Night Of Loot: One Man's Treasure}}
|OGDA
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20416-fan-mission-a-night-of-loot-one-mans-treasure/}}
|2020-06-13
|3.9
|No
|No
|No
|
|Shop/House
|
|-

|-
!align=left|{{TDM-FM|good|A Good Neighbor}}
|Amadeus
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20292-fan-mission-a-good-neighbor/}}
|2020-03-08
|54.6
|Yes
|No
|No
|
|City Missions <br> Inn/Tavern
|
|-

|-
!align=left|{{TDM-FM|airpocket|Away 1 - Air Pocket}}
|Geep
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20252-fan-mission-away-1-air-pocket-by-geep-20200207}}
|2020-02-06
|15.3
|No
|No
|No
|[[Fan_Mission_Series#Away_series|Away]]
|Pirate <br> Ship
|
|-

|-
!align=left|{{TDM-FM|snowed_inn|Snowed Inn}}
|Goldwell and Kingsal
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20201-fan-mission-snowed-inn-by-goldwell-kingsal-20191225}}
|2019-12-25
|382
|Yes
|No
|No
|
|City Missions
|
|-

|-
!align=left|{{TDM-FM|indangerofjudgment|In Danger of Judgment}}
|krrg
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20155-fan-mission-in-danger-of-judgment-20191115/}}
|2019-11-15
|11.9
|No
|No
|No
|
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|lhl|Langhorne Lodge}}
|Bienie
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20143-fan-mission-langhorne-lodge/}}
|2019-10-30
|8.2
|Yes
|No
|No
|
|Mansion/Estate
|Undead <br> Ghosts <br> Spiders
|-

|-
!align=left|{{TDM-FM|heartstmattis|The Heart of Saint Mattis}}
|joebarnin
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20091-fan-mission-the-heart-of-saint-mattis-by-joebarnin-20190910/}}
|2019-09-10
|58.7
|Yes
|No
|No
|
|Church/Cathedral
|Spiders, Undead, Horror Themes
|-

|-
!align=left|{{TDM-FM|peril|Perilous Refuge}}
|Dragofer, Crucible Team
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20090-fan-mission-perilous-refuge-by-dragofer-20190910/}}
|2019-09-10
|34.7
|Yes
|No
|No
|
|Ship, City Missions
|
|-

|-
!align=left|{{TDM-FM|hhvf|Hidden Hands: Vitalic Fever}}<br>(v6, 2025/04/20)
|JackFarmer
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20051-hidden-hands-vitalic-fever-20072019}}
|2019-07-20
|269
|Yes
|No
|Yes
|[[Fan_Mission_Series#Hidden_Hands_series|Hidden Hands]]
|Mansion/Estate
|Spiders, Undead
|-

|-
!align=left|{{TDM-FM|cos2_precpos|Chronicles of Skulduggery 2: A Precarious Position}}
|Bienie
|{{Forumlink|https://forums.thedarkmod.com/topic/19975-fan-mission-chronicles-of-skulduggery-2-a-precarious-position-20190504/}}
|2019-05-04
|14.5
|Yes
|No
|No
|[[Fan_Mission_Series#Chronicles_of_Skulduggery_series|Chronicles of Skulduggery]]
|City Missions
|
|-

|-
!align=left|{{TDM-FM|ws5_commerce|William Steele 5: Commerce Bank}}
|grayman
|{{Forumlink|https://forums.thedarkmod.com/topic/19957-fan-mission-commerce-bank-by-grayman-2019410/}}
|2019-04-10
|30
|Yes
|No
|Yes
|[[Fan_Mission_Series#William_Steele_series|William Steele]]
|Bank Jobs
|
|-

|-
!align=left|{{TDM-FM|marshofrahena|Marsh of Rahena}}
|ERH+
|{{Forumlink|https://forums.thedarkmod.com/topic/19951-fan-mission-marsh-of-rahena-by-erh-201945}}
|2019-04-05
|60.3
|Yes
|No
|No
|
|Castle/Fortress, Horror
|Spiders, Undead, Horror Themes
|-

|-
!align=left|{{TDM-FM|northdale2|Shadows of Northdale ACT 2}}
|Goldwell
|{{Forumlink|https://forums.thedarkmod.com/topic/19936-fan-mission-shadows-of-northdale-act-ii-by-goldwell-20190320/}} [https://www.youtube.com/watch?v=KO-eIOX9nqI Briefing]
|2019-03-20
|417
|Yes
|No
|No
|[[Fan_Mission_Series#Shadows of Northdale series|Shadows of Northdale]]
|City Missions
|Undead
|-

|-
!align=left|{{TDM-FM|cleanneighbourhood|Cleaning Up the Neighbourhood}}
|some1stoleit and Bikerdude
|{{Forumlink|https://forums.thedarkmod.com/topic/19898-fan-mission-cleaning-up-the-neighbourhood-by-some1stoleitbikerdude-20190219/}}
|2019-02-18
|34.3
|No
|No
|No
|
|City Missions
|
|-

|-
!align=left|{{TDM-FM|hhi|Hidden Hands: Initiation}}
|JackFarmer
|{{Forumlink|https://forums.thedarkmod.com/topic/19796-hidden-hands-initiation-27122018/}}
|2018-12-27
|92.5
|Yes
|No
|No
|[[Fan_Mission_Series#Hidden_Hands_series|Hidden Hands]]
|Mansion/Estate <br>Ship
|Spiders, Extra-natural entities
|-

|-
!align=left|{{TDM-FM|reluctantbenefaction|The Night of Reluctant Benefaction}}
|Bienie
|{{Forumlink|https://forums.thedarkmod.com/topic/19787-fan-mission-the-night-of-reluctant-benefaction/}}
|2018-12-24
|11.9
|Yes
|No
|No
|
|City Missions
|
|-

|-
!align=left|{{TDM-FM|mercwarehouse|Mission of Mercy}}
|joebarnin
|{{Forumlink|https://forums.thedarkmod.com/topic/19642-fan-mission-mission-of-mercy-by-joebarnin-20180914/}}
|2018-09-14
|10.1
|No
|No
|No
|
|Warehouse
|
|-

|-
!align=left|{{TDM-FM|ws4_warrens|William Steele 4: The Warrens}}
|grayman
|{{Forumlink|https://forums.thedarkmod.com/topic/19618-fan-mission-the-warrens-by-grayman-201891/}}
|2018-09-01
|53
|Yes
|No
|Yes
|[[Fan_Mission_Series#William_Steele_series|William Steele]]
|City Missions
|
|-

|-
!align=left|{{TDM-FM|braeden_church|Braeden Church}}
|grayman
|{{Forumlink|https://forums.thedarkmod.com/topic/19533-fan-mission-braeden-church-by-grayman-201871/}}
|2018-07-01
|24
|No
|No
|Yes
|
|Mansion/Estate
|Undead
|-

|-
!align=left|{{TDM-FM|pearlsnswine|Chronicles of Skulduggery: Pearls and Swine}}
|Bienie
|{{Forumlink|https://forums.thedarkmod.com/topic/19439-chronicles-of-skulduggery-pearls-and-swine/}}
|2018-05-25
|23
|Yes
|No
|Yes
|[[Fan_Mission_Series#Chronicles_of_Skulduggery_series|Chronicles of Skulduggery]]
|City Missions
|
|-

|-
!align=left|{{TDM-FM|northdale1|Shadows of Northdale ACT I}}
|Goldwell
|{{Forumlink|https://forums.thedarkmod.com/topic/19368-fan-mission-shadows-of-northdale-act-i-by-goldwell-20180323/}} [https://www.youtube.com/watch?v=p4nP3lYd6wg Briefing]
|2018-03-23
|295
|Custom <br>(not EFX)
|No
|No
|[[Fan_Mission_Series#Shadows of Northdale series|Shadows of Northdale]]
|City Missions
|
|-

|-
!align=left|{{TDM-FM|sirt|Sir Taffsalot's Sword}}
|grayman
|{{Forumlink|https://forums.thedarkmod.com/topic/19361-fan-mission-sir-taffsalots-sword-by-grayman-2018318/}}
|2018-03-17
|11.3
|No
|No
|No
|
|Mansion/Estate <br> <br> In memoriam of Gary (Sir Taffsalot) {{Forumlink|https://forums.thedarkmod.com/topic/19306-sad-news-we-lost-one-of-our-own-sir-taffsalot/}}
|
|-

|-
!align=left|{{TDM-FM|arena|The Arena}}
|ERH+
|{{Forumlink|https://forums.thedarkmod.com/topic/19350-fan-mission-the-arena-by-erh/}}
|2018-03-12
|3
|No
|No
|No
|
|Arena Deathmatch <br> Experimental
|Spiders, Undead
|-

|-
!align=left|{{TDM-FM|elixir|The Elixir}}
|Bikerdude and Obsttorte
|{{Forumlink|https://forums.thedarkmod.com/topic/19323-fan-mission-the-elixir-by-b1k3rdude-obsttorte-17022018/}} [https://www.youtube.com/watch?v=KfElYZs-FaE Briefing]
|2018-02-17
|112
|Yes
|No
|Yes
|Elixir
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|cauldron_v2_2|Volta 2: Cauldron of the Gods}}
|Kingsal
|{{Forumlink|https://forums.thedarkmod.com/topic/19207-volta-ii-cauldron-of-the-gods/}} [https://www.youtube.com/watch?v=SRRCRVFHruc Briefing]
|2017-11-30
|252
|Yes
|No
|No
|[[Fan_Mission_Series#Volta series|Volta]]
|Lost Civilizations
|Undead
|-

|-
!align=left|{{TDM-FM|itb|In the Black}}
|VanishedOne
|{{Forumlink|https://forums.thedarkmod.com/topic/19185-fan-mission-in-the-black/}}
|2017-11-18
|103
|No
|No
|No
|
|Mansion/Estate
|Undead
|-

|-
!align=left|{{TDM-FM|ac1|Accountant 1: Thieves and Heirs}}
|Goldwell
|{{Forumlink|https://forums.thedarkmod.com/topic/19164-fan-mission-the-accountant-1-thieves-and-heirs-by-goldwell-20171108}} [https://www.youtube.com/watch?v=Tk9DtOT4kjc Briefing]
|2017-11-08
|247
|No
|Yes <br><br>(Darkfate version is better for Russian players, fully dubbed audio)
|No
|[[Fan_Mission_Series#The Accountant series|The Accountant]]
|Mansion/Estate
|Spiders
|-

|-
!align=left|{{TDM-FM|kotm|King of the Mountain}}
|Spoonman
|{{Forumlink|https://forums.thedarkmod.com/topic/19105-fan-mission-king-of-the-mountain-by-spoonman-18092017/}}
|2017-09-18
|8.07
|No
|No
|No
|
|Jail/Prison
|
|-

|-
!align=left|{{TDM-FM|briarwood_manor|Briarwood Manor}}
|NeonStyle
|{{Forumlink|https://forums.thedarkmod.com/topic/18980-fan-mission-briarwood-manor-by-neonsstyle-first-mission-2017-07-11}} [https://www.youtube.com/watch?v=BZnSuLVatYM Trailer] [https://www.youtube.com/watch?v=CPlu8fEzyGM Briefing]
|2017-07-11
|90
|No
|No
|No
|
|Mansion/Estate
|Spider
|-

|-
!align=left|{{TDM-FM|matterofhours|A Matter of Hours}}
|Springheel
|{{Forumlink|https://forums.thedarkmod.com/topic/18809-fan-mission-a-matter-of-hours-by-springheel-2842017/}}
|2017-04-28
|13
|No
|Yes
|No
|[[Fan Mission Series#Corbin series|Corbin]]
|Warehouse
|
|-

|-
!align=left|{{TDM-FM|ravine|The Ravine}}
|Spoonman
|{{Forumlink|https://forums.thedarkmod.com/topic/18782-fan-mission-the-ravine-by-spoonman-17042017/}}
|2017-04-17
|30.6
|No
|Yes
|No
|
|Outdoor/Pagan
|Spiders
|-

|-
!align=left|{{TDM-FM|bakery_job|The Bakery Job}}
|Sotha
|{{Forumlink|https://forums.thedarkmod.com/topic/18707-fan-mission-the-bakery-job-by-sotha-20170309/}}
|2017-03-09
|2
|No
|Yes
|No
|
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM||Mission 1: A New Job}}
|Springheel
|{{Forumlink|https://forums.thedarkmod.com/topic/18647-tdm-205-official-introductory-missions/}}
|2017-03-14
|13.8
|Yes
|
|Yes
|[[Fan_Mission_Series#Introduction_campaign|Official Campaign]]
|City Missions <br> Inn/Tavern
|
|-

|-
!align=left|{{TDM-FM|coercion|Coercion}}
|Sotha
|{{Forumlink|https://forums.thedarkmod.com/topic/18405-fan-mission-coercion-by-sotha-20160927}}
|2016-09-27
|10
|No
|Yes
|Yes
|
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|river|Down by the Riverside}}
|Dragofer
|{{Forumlink|https://forums.thedarkmod.com/topic/18402-fan-mission-down-by-the-riverside-by-dragofer-20160925}}
|2016-09-25
|56
|No
|No
|Yes
|[[Fan_Mission_Series#Of Brambles and Thorns series|Of Brambles and Thorns]]
|Mansion/Estate <br> Ship <br> Horror
|Horror themes, Undead
|-

|-
!align=left|{{TDM-FM|penny3|Penny Dreadful 3: Erasing the Trail}}
|Melan and Bikerdude
|{{Forumlink|https://forums.thedarkmod.com/topic/18200-fan-mission-penny-dreadful-3-by-melan-and-bikerdude-20160710}}
|2016-07-09
|200
|No
|No
|No
|[[Fan_Mission_Series#Penny Dreadful series|Penny Dreadful]]
|City Missions
|
|-

|-
!align=left|{{TDM-FM|volta1_3|Volta 1: Volta and the Stone}}
|Kingsal
|{{Forumlink|https://forums.thedarkmod.com/topic/18087-fan-mission-volta-and-the-stone-by-kingsal-05262016}}
|2016-05-27
|102
|Yes
|Yes
|No
|[[Fan_Mission_Series#Volta series|Volta]]
|Mansion/Estate <br> City Missions
|
|-

|-
!align=left|{{TDM-FM|fever|Full Moon Fever}}<br>(v2.0 2018/02/21)
|Spoonman
|{{Forumlink|https://forums.thedarkmod.com/topic/18066-fan-mission-full-moon-fever-by-spoonman-14052016/}}
|2016-05-14
|21
|No
|Yes
|No
|
|Mansion/Estate
|Undead
|-

|-
!align=left|{{TDM-FM|kingofdiamonds|King of Diamonds}}
|Spooks
|{{Forumlink|https://forums.thedarkmod.com/topic/18064-fan-mission-the-king-of-diamonds-by-spooks-20160513}}
|2016-05-13
|26.3
|No
|No
|No
|
|City Missions
|Occult themes
|-

|-
!align=left|{{TDM-FM|ac2|Accountant 2: New in Town}}
|Goldwell
|{{Forumlink|https://forums.thedarkmod.com/topic/18054-fan-mission-the-accountant-2-new-in-town-by-goldwell-20160509/}} [https://www.youtube.com/watch?v=xeuIO_GcYjQ Briefing] <br> [https://www.youtube.com/watch?v=w6e_SJ0_JOM Gameplay trailer]
|2016-05-08
|358
|No
|Yes
|No
|[[Fan_Mission_Series#The Accountant series|The Accountant]]
|Mansion/Estate
|Undead
|-

|-
!align=left|{{TDM-FM|cutpurse|The Smiling Cutpurse}}
|Airship Ballet
|{{Forumlink|https://forums.thedarkmod.com/topic/17850-fan-mission-the-smiling-cutpurse-by-airship-ballet-20160325/}}
|2016-03-25
|87
|No
|Yes
|No
|
|Mansion/Estate <br> Sewers
|
|-

|-
!align=left|{{TDM-FM|mother|Mother Rose}}
|grayman
|{{Forumlink|https://forums.thedarkmod.com/topic/17653-fan-mission-mother-rose-by-grayman-20160101/#entry385131/}}
|2016-01-01
|10
|No
|Yes
|No
|
|Mansion/Estate
|Ghost
|-

|-
!align=left|{{TDM-FM|bcd|Behind Closed Doors}}
|Bikerdude and the Crucible Team
|{{Forumlink|https://forums.thedarkmod.com/topic/17627-crucible-of-omens-behind-closed-doors-by-bikerdude-the-crucible-team-updated-18122015/}}
|2015-12-19
|359
|Yes
|Yes
|No
|[[Fan_Mission_Series#Crucible of Omens series|Crucible of Omens]]
|City Missions
|
|-

|-
!align=left|{{TDM-FM|theratst|The Rats Triumphant}}
|Melan
|{{Forumlink|https://forums.thedarkmod.com/topic/17512-fan-mission-the-rats-triumphant-by-melan-20151031/}}
|2015-10-31
|11
|No
|Yes
|No
|[[Fan_Mission_Contests#2015_Halloween_Speed-build_Contest|HSC 15]] '''WINNER'''
|City Missions
|Undead
|-

|-
!align=left|{{TDM-FM|deaddrunk|Dead Drunk}}
|Stumpy
|{{Forumlink|https://forums.thedarkmod.com/topic/17511-fan-mission-dead-drunk-by-stumpy-20151030/}}
|2015-10-30
|4
|No
|Yes
|No
|[[Fan_Mission_Contests#2015_Halloween_Speed-build_Contest|HSC 15]]
|Tombs, Catacombs & Crypts
|Undead
|-

|-
!align=left|{{TDM-FM|remorse|Thief's Remorse}}
|Airship Ballet
|{{Forumlink|https://forums.thedarkmod.com/topic/17509-fan-mission-thiefs-remorse-by-airship-ballet-20151030/}}
|2015-10-30
|42
|No
|Yes
|No
|[[Fan_Mission_Contests#2015_Halloween_Speed-build_Contest|HSC 15]]
|Tombs, Catacombs & Crypts
|Undead
|-

|-
!align=left|{{TDM-FM|springcleaning|Spring Cleaning}}
|Goldwell
|{{Forumlink|https://forums.thedarkmod.com/topic/17510-fan-mission-spring-cleaning-by-goldwell-20151030/}} [https://www.youtube.com/watch?v=JzPpmDK9Fxw Briefing]
|2015-10-30
|45
|No
|Yes
|Yes
|[[Fan_Mission_Contests#2015_Halloween_Speed-build_Contest|HSC 15]]
|Mansion/Estate
|Spiders, Undead
|-

|-
!align=left|{{TDM-FM|the_golden_skull|The Golden Skull}}
|Sotha
|{{Forumlink|https://forums.thedarkmod.com/topic/17497-fan-mission-the-golden-skull-by-sotha-20151024/}}
|2015-10-25
|7
|No
|Yes
|No
|[[Fan_Mission_Contests#2015_Halloween_Speed-build_Contest|HSC 15]]
|Mansion/Estate
|Undead
|-

|-
!align=left|{{TDM-FM|ahouseoflockedsecrets|A House of Locked Secrets}}
|Moonbo
|{{Forumlink|https://forums.thedarkmod.com/topic/17163-fan-mission-a-house-of-locked-secrets-by-gelo-moonbo-fleisher-20150528/}} [https://www.youtube.com/watch?v=f5NuTJEZ8VE Trailer]
|2015-05-29
|195
|No
|Yes
|Yes
|[[Fan_Mission_Series#Shadowcursed series|Shadowcursed]]
|Church/Cathedral <br> Mansion/Estate
|Horror themes, <br> Undead
|-

|-
!align=left|{{TDM-FM|u2_flock|Ulysses 2: Protecting the Flock}}
|Sotha
|{{Forumlink|https://forums.thedarkmod.com/topic/17162-fan-mission-ulysses-2-protecting-the-flock-by-sotha-20150528/}}
|2015-05-28
|102
|No
|Yes
|No
|[[Fan_Mission_Series#Ulysses series|Ulysses]]
|Church/Cathedral
|
|-

|-
!align=left|{{TDM-FM|talbot|Sir Talbot's Collateral}}<br>(v6 2024/01/29)
|Baal and Bikerdude
|{{Forumlink|https://forums.thedarkmod.com/topic/17093-fan-mission-sir-talbots-collateral-by-baal-bikerdude-15042015/}} [https://www.youtube.com/watch?v=e3rdZfq4Omc Trailer]
|2015-04-15
|60
|Yes
|Yes
|Yes
|[[Fan_Mission_Series#Sir Talbot series|Sir Talbot]]
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|vfat3|Vengeance for a Thief Part 3}}
|Sir Taffsalot
|{{Forumlink|https://forums.thedarkmod.com/topic/16953-the-complete-vengeance-for-a-thief-campaign/}}
|2015-02-16
|25
|No
|Yes
|No
|[[Fan_Mission_Series#Vengeance for a Thief series|VFAT]]
|Church/Cathedral
|
|-

|-
!align=left|{{TDM-FM|bathhouse|Lord Edgar's Bathhouse}}
|Goldwell
|{{Forumlink|1=https://forums.thedarkmod.com/topic/16828-fan-mission-lord-edgars-bathhouse-by-goldwell-27122014/}} [https://www.youtube.com/watch?v=vYSZY7VzFEo Briefing]
|2014-12-27
|71
|No
|Yes
|Yes
|Lord Edgar
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|quinn|Quinn Co.}}<br>(Made into a campaign, 2015/02/04)<br>{{TDM-FM|m_lbb|La Banque Bienveillante}} {{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/21488-fan-mission-quinn-co-part-1-la-banque-bienveillante-remake-by-airship-ballet}}<br>(Re-Release, 2022/06/24)
|Airship Ballet
|{{Forumlink|1=https://forums.thedarkmod.com/topic/16912-fan-mission-chase-mercantile-by-airship-ballet-20150204/}}
|2014-11-22
|111
|No
|Yes : Quinn<br><br>No : Part 1
|No
|Quinn Co.
|Bank Jobs
|
|-

|-
!align=left|{{TDM-FM|exhumed|Exhumed}}
|Airship Ballet and Kyyrma
|{{Forumlink|1=https://forums.thedarkmod.com/topic/16658-fan-mission-exhumed-by-kyyrma-and-airship-ballet-20141104/}}
|2014-11-04
|24
|No
|Yes
|No
|[[Fan_Mission_Contests#2014 Halloween Speed-build Contest|HSC 14]]
|Church/Cathedral <br> Horror
|Undead
|-

|-
!align=left|{{TDM-FM|briarwood|Briarwood Cathedral}}
|buck28
|{{Mirrorlink|https://www64.zippyshare.com/v/25705489/file.html}}{{Forumlink|1=https://forums.thedarkmod.com/topic/16644-briarwood-cathedral/}}
|2014-10-29
|7
|No
|Yes
|No
|[[Fan_Mission_Series#Master thief Corso series|Corso]] <br> [[Fan_Mission_Contests#2014 Halloween Speed-build Contest|HSC 14]] '''WINNER'''
|Church/Cathedral <br> Horror
|Undead
|-

|-
!align=left|{{TDM-FM|onesteptoofar|One Step Too Far}}<br>(v2.0 2023/06/18)
|Dragofer
|{{Mirrorlink|https://www.dropbox.com/s/sfxcap1gfdzf318/onesteptoofar.pk4}}{{Forumlink|1=https://forums.thedarkmod.com/topic/16457-fan-mission-one-step-too-far-by-dragofer-20140804/}}
|2014-08-04
|9
|No
|Yes
|Yes
|[[Fan_Mission_Series#Of Brambles and Thorns series|Of Brambles and Thorns]]
|Pirate <br> Ship
|
|-

|-
!align=left|{{TDM-FM|lockner|Lockner Manor}}
|buck28
|{{Mirrorlink|https://www76.zippyshare.com/v/44108372/file.html}}{{Forumlink|1=https://forums.thedarkmod.com/topic/16452-new-mission-lockner-manor/}}
|2014-08-02
|6
|No
|Yes
|No
|[[Fan_Mission_Series#Master thief Corso series|Corso]]
|Mansion/Estate <br> Inn/Tavern
|
|-

|-
!align=left|{{TDM-FM|ulysses_genesis|Ulysses: Genesis}}
|Sotha
|{{Mirrorlink|https://www4.zippyshare.com/v/67195436/file.html}}{{Forumlink|1=https://forums.thedarkmod.com/topic/16428-fan-mission-ulysses-genesis-by-sotha-20140724/}}
|2014-07-24
|98
|No
|Yes
|Yes
|[[Fan_Mission_Series#Ulysses series|Ulysses]]
|Mansion/Estate
|Horror theme?
|-

|-
!align=left|{{TDM-FM|penny2_1|Penny Dreadful 2: All the way up}}
|Melan and Bikerdude
|{{Mirrorlink|https://mega.co.nz/#!EwoXHZYZ!tE_sKon2h4AWtWPNt9QS3FQClwmXdimhfjIMPcpCQ34}}{{Forumlink|1=https://forums.thedarkmod.com/topic/16387-fan-mission-penny-dreadful-2-by-melan-and-bikerdude-2014078/}} [https://www.youtube.com/watch?v=WmPfCfbeWvg Trailer]
|2014-07-08
|102
|No
|Yes
|No
|[[Fan_Mission_Series#Penny Dreadful series|Penny Dreadful]]
|Thieves' Highway / Rooftop
|Spiders
|-

|-
!align=left|{{TDM-FM|poets|Poets and Peasants}}
|Digi
|{{Mirrorlink|https://drive.google.com/file/d/0B1HHvWAgbWGfTkI0SXFubXZucXM}}{{Forumlink|1=https://forums.thedarkmod.com/topic/16373-fan-mission-poets-peasants-by-digi-62914}}
|2014-06-29
|1
|No
|Yes
|No
|
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|follow|A Reputation to Uphold}}
|Springheel
|{{Mirrorlink|https://www.mindplaces.com/follow.pk4}}{{Forumlink|1=https://forums.thedarkmod.com/topic/16204-fan-mission-a-reputation-to-uphold-by-springheel/}}
|2014-04-18
|25.5
|No
|Yes
|No
|[[Fan_Mission_Series#Corbin series|Corbin]]
|City Missions
|
|-

|-
!align=left|{{TDM-FM|breakingout|Breaking Out the Fence}}
|Kyyrma
|{{Mirrorlink|https://dl.dropboxusercontent.com/u/17706561/breakingout.pk4}}{{Forumlink|1=https://forums.thedarkmod.com/topic/16091-fan-mission-breaking-out-the-fence-17032014-by-kyyrma/}}
|2014-03-17
|11.6
|No
|Yes
|No
|[[Fan_Mission_Series#In A Time of Need series|In A Time of Need]]
|City Missions <br> Jail/Prison
|
|-

|-
!align=left|{{TDM-FM|innbiz|Inn Business}}<br>(v.1.48, 2014/03/08)
|RJFerret
|{{Mirrorlink|https://drive.google.com/file/d/0B81T2ZXLPqhTYWVaODRiSExGeGc}} {{Forumlink|1=https://forums.thedarkmod.com/topic/16018-fan-mission-inn-business-by-rjferret-20140303/}}
|2014-03-03
|6
|No
|Yes
|No
|
|Inn/Tavern <br> City Streets
|
|-

|-
!align=left|{{TDM-FM|ws3_cleighmoor|William Steele 3: Cleighmoor}}
|grayman
|{{Forumlink|https://forums.thedarkmod.com/topic/16011-fan-mission-cleighmoor-by-grayman-201431/#entry338349/}}
|2014-03-01
|38
|No
|Yes
|Yes
|[[Fan_Mission_Series#William Steele series|William Steele]]
|Sewers <br> Jail/Prison
|
|-

|-
!align=left|{{TDM-FM|ws2_homeagain|William Steele 2: Home Again}}
|grayman
|{{Forumlink|https://forums.thedarkmod.com/topic/15919-fan-mission-home-again-by-grayman-2014212/page__fromsearch__1}}
|2014-02-12
|26
|No
|Yes
|Yes
|[[Fan_Mission_Series#William Steele series|William Steele]]
|Thieves' Highway / Rooftop
|
|-

|-
!align=left|{{TDM-FM|gatehouse1_3|The Gatehouse}}
|Bikerdude Goldchocobo
|{{Mirrorlink|https://www.southquarter.com/tdm/fms/gatehouse.pk4}} {{Forumlink|https://forums.thedarkmod.com/topic/15844-fan-mission-the-gatehouse-by-bikerdude-goldchocobo-20140114/}} [https://www.youtube.com/watch?v=kcIe2Ucojqw Briefing]
|2014-01-29
|100
|No
|Yes
|Yes
|Remake of Evilartist's Doom 3 mod
|Castle/Fortress
|Ghosts
|-

|-
!align=left|{{TDM-FM|windowopportunity|Window of Opportunity}}<br>(v.1.43, 2014/01/01)
|RJFerret
|{{Mirrorlink|https://drive.google.com/file/d/0B81T2ZXLPqhTWTMzQXZtMVFBSG8}} {{Forumlink|1=https://forums.thedarkmod.com/topic/15727-fan-mission-window-of-opportunity-by-rjferret-20140101/}}
|2014-01-01
|7
|No
|Yes
|No
|
|Outdoor/Caves
|Spiders (not in short mode)
|-

|-
!align=left|{{TDM-FM|timeofneed|In A Time Of Need}}
|kyyrma
| {{Mirrorlink|https://www.mediafire.com/download/a97or40t1xrybh3/timeofneed_v1.zip}} {{Forumlink|https://forums.thedarkmod.com/topic/15354-fan-mission-in-a-time-of-need-by-kyyrma-20131112/}}
|2013-11-12
|5.6
|No
|Yes
|No
|[[Fan_Mission_Series#In A Time of Need series|In A Time of Need]]
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|requiem|Requiem}}
|Moonbo
| {{Mirrorlink|https://www.mediafire.com/download/l6o3vvj9y78hu89/requiem.pk4}} {{Forumlink|https://forums.thedarkmod.com/topic/15101-fan-mission-requiem-by-gelo-moonbo-fleisher-2013106/}}
|2013-10-08
|107.3
|Yes
|Yes
|Yes
|[[Fan_Mission_Series#Shadowcursed series|Shadowcursed]]
|Lost Civilizations <br> Church/Cathedral
|Undead
|-

|-
!align=left|{{TDM-FM|vfat2|Vengeance for a Thief Part 2}}
|Sir Taffsalot
| {{Mirrorlink|https://dl.dropboxusercontent.com/u/17706561/vfat2.pk4}} {{Forumlink|https://forums.thedarkmod.com/topic/15051-fan-mission-vengeance-for-a-thief-part-2-by-sir-taffsalot-06092013/}}
|2013-09-06
|22
|No
|Yes
|No
|[[Fan_Mission_Series#Vengeance for a Thief series|VFAT]] <br> [[Fan_Mission_Contests#2013 Community Unusual Contest|CUC 13]]
|Museum Heists
|
|-

|-
!align=left|{{TDM-FM|lordsnlegacy|Lords and Legacy}}
|Kvorning
| {{Mirrorlink|https://dl.dropboxusercontent.com/u/17706561/lordsnlegacy.pk4}} {{Forumlink|https://forums.thedarkmod.com/topic/15016-fan-mission-lords-legacy-by-kvorning-20130830/}}
|2013-08-30
|45
|No
|Yes
|No
|
|Thieves' Highway / Rooftop
|
|-

|-
!align=left|{{TDM-FM|naog|Not An Ordinary Guest}}
|DeTeEff (Fieldmedic)
| {{Mirrorlink|https://dl.dropboxusercontent.com/u/17706561/naog.pk4}} {{Forumlink|https://forums.thedarkmod.com/topic/14965-fan-mission-not-an-ordinary-guest-by-fieldmedic-20130801/}}
|2013-08-01
|79.6
|No
|Yes
|No
|[[Fan_Mission_Contests#2013 Community Unusual Contest|CUC 13]]
|City Missions
|
|-

|-
!align=left|{{TDM-FM|penny1_1|Penny Dreadful: Grail of Regrets}}
|Melan
| {{Forumlink|https://forums.thedarkmod.com/topic/14952-fan-mission-penny-dreadful-by-melan-20130728/}}
|2013-07-27
|74
|No
|Yes
|No
|[[Fan_Mission_Series#Penny Dreadful series|Penny Dreadful]]
|Horror
|Spiders, Undead
|-

|-
!align=left|{{TDM-FM|solarescape1|Solar Escape 1}}
|Tr00pertj
| {{Forumlink|https://forums.thedarkmod.com/topic/14944-fan-mission-solar-escape-1/}}
|2013-07-22
|6
|No
|Yes
|No
|
|Mansion/Estate <br> Sewers
|Spiders, Undead
|-

|-
!align=left|{{TDM-FM|lich_queens_demise|The Lich Queen's Demise}}
|Sotha
|{{Mirrorlink|https://dl.dropboxusercontent.com/u/17706561/lich_queens_demise.pk4}} {{Forumlink|https://forums.thedarkmod.com/topic/14826-fan-mission-the-lich-queens-demise-by-sotha-20130520/unread/}}
|2013-05-20
|97.6
|No
|Yes
|No
|[[Fan_Mission_Series#Thomas Porter series|Thomas Porter]] <br> [[Fan_Mission_Contests#2013 Community Unusual Contest|CUC 13]] '''WINNER'''
|Horror
|Undead
|-

|-
!align=left|{{TDM-FM|oldhabits2|Old Habits Rebuild}}
|Obsttorte
|{{Mirrorlink|https://www.mediafire.com/download/u2gwucibh17c45a/oldhabits.pk4}} {{Forumlink|https://forums.thedarkmod.com/topic/14827-fan-mission-old-habits-rebuild-by-obsttorte-20052013/}}
|2013-05-20
|28.6
|No
|Yes
|No
|
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|builders_blocks|The Builder's Blocks}}
|Jesps
|{{Mirrorlink|https://dl.dropboxusercontent.com/u/17706561/builders_blocks.pk4}} {{Forumlink|https://forums.thedarkmod.com/topic/14592-unusual-gameplay-contest-fm-the-builders-blocks-by-jesps/}}
|2013-03-18
|2.85
|No
|Yes
|No
|[[Fan_Mission_Contests#2013 Community Unusual Contest|CUC 13]]
|Experimental
|
|-

|-
!align=left|{{TDM-FM|broads|The Builder Roads}}
|Obsttorte
|{{Forumlink|https://forums.thedarkmod.com/topic/14449-fan-mission-the-builder-roads-by-obsttorte-20130119/}}
|2013-01-19
|2.3
|No
|Yes
|No
|
|Church/Experimental
|-

|-
!align=left|{{TDM-FM|ws1_north|William Steele 1: In the North}}
|grayman
|{{Forumlink|https://forums.thedarkmod.com/topic/14214-fan-mission-in-the-north-by-grayman-20121020/}}
|2012-10-20
|39.8
|No
|Yes
|Yes
|[[Fan_Mission_Series#William Steele series|William Steele]]
|Mansion/Estate
|Undead
|-

|-
!align=left|{{TDM-FM|oldhabits1|Old Habits}}
|Obsttorte
|{{Mirrorlink|https://www.mediafire.com/download.php?andes2xnsonssfj}} {{Forumlink|https://forums.thedarkmod.com/topic/14206-fan-mission-old-habits-by-obsttorte-20121019/}}
|2012-10-19
|12.8
|No
|Yes
|No
|
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|deceptiveshadowsv1_2|Deceptive Shadows}}
|ShadowHide
|{{Mirrorlink|https://www.sendspace.com/file/jzr9s7}} {{Forumlink|https://forums.thedarkmod.com/topic/14103-fan-mission-deceptive-shadows-by-shadowhide-16sep12/}}
|2012-09-16
|22.4
|No
|Yes
|Yes
|
|Outdoor/Pagan
|Spiders, Undead
|-

|-
!align=left|{{TDM-FM|vfat1|Vengeance for a Thief: Part 1}}
|Sir Taffsalot
|{{Mirrorlink|https://dl.dropbox.com/u/17706561/VFAT1.pk4}} {{Forumlink|https://forums.thedarkmod.com/topic/14068-fan-mission-vengeance-for-a-thief-part-1-by-sir-taffsalot-06092012/}}
|2012-09-06
|20.9
|No
|Yes
|No
|[[Fan_Mission_Series#Vengeance for a Thief series|VFAT]]
|Jail/Prison
|
|-

|-
!align=left|{{TDM-FM|phrase_book|The Phrase Book}}
|Sotha
|{{Mirrorlink|https://dl.dropbox.com/u/17706561/phrase_book.pk4}} {{Forumlink|https://forums.thedarkmod.com/topic/13799-fan-mission-the-phrase-book-by-sotha-20120512/}}
|2012-05-11
|24
|No
|Yes
|No
|[[Fan_Mission_Series#Thomas Porter series|Thomas Porter]]
|Thieves' Highway / Rooftop
|
|-

|-
!align=left|{{TDM-FM|remembrance|In Remembrance of Him}}
|RPGista
|{{Mirrorlink|https://dl.dropbox.com/u/17706561/remembrance.pk4}} {{Forumlink|https://forums.thedarkmod.com/topic/13749-fan-mission-in-remembrance-of-him-by-rpgista/}}
|2012-04-22
|27.6
|No
|Yes
|No
|[[Fan_Mission_Contests#2012_Community_Beginner_Contest|CBC 12]]
|City Missions
|Undead
|-

|-
!align=left|{{TDM-FM|rightful|Rightful Property}}
|jysk
|{{Mirrorlink|https://dl.dropbox.com/u/17706561/rightful1.1b.pk4}} {{Forumlink|https://forums.thedarkmod.com/topic/13711-fan-mission-rightful-property-by-jysk-20120413/}}
|2012-04-12
|22.5
|No
|Yes
|No
|[[Fan_Mission_Contests#2012_Community_Beginner_Contest|CBC 12]]
|Bank Jobs
|Spiders
|-

|-
!align=left|{{TDM-FM|sneak_destroy|Sneak & Destroy}}<br>(v2 EFX, 2022/11/16)
|SeriousToni
|{{Mirrorlink|https://minus.com/mVcf61n3G/1f}} {{Forumlink|https://forums.thedarkmod.com/topic/13706-fan-mission-sneak-destroy-by-serioustoni-beginners-contest-2012/}}
|2012-04-11
|147
|Yes
|Yes
|Yes
|[[Fan_Mission_Contests#2012_Community_Beginner_Contest|CBC 12]] '''WINNER'''
|City Missions
|
|-

|-
!align=left|{{TDM-FM|houseoftheo|House of Theo}}
|Theothesnopp
|{{Mirrorlink|https://www.gamefront.com/files/21053391/houseoftheo__2__2.pk4}} {{Forumlink|https://forums.thedarkmod.com/topic/13242-fan-mission-house-of-theo/}}
|2011-12-04
|6.2
|No
|Yes
|No
|
|Castle/Fortress
|
|-

|-
!align=left|{{TDM-FM|crystalgrave2_1|Crystal Grave}} <br>(v.2.0, 2013/02/09)
|ERH+ Bikerdude
|{{Mirrorlink|https://dl.dropbox.com/u/17706561/crystalgravev2.pk4}} {{Forumlink|https://forums.thedarkmod.com/topic/14510-fan-mission-crystal-grave-v2-by-erh-and-bikerdude-20130209/unread/}}
|2011-11-15
|12.4
|No
|Yes
|No
|
|Horror
|Undead
|-

|-
!align=left|{{TDM-FM|claw1_31|Dragon's Claw}}<br>(v1.31, 2020/11/02)
|Bikerdude, Flanders (map assets)
|{{Mirrorlink|https://www.gamefront.com/files/20948800/claw.pk4}} {{Forumlink|https://forums.thedarkmod.com/topic/13181-fan-missiondragons-claw-by-b1k3rdude-31102011/}}
|2011-10-31
|98
|No
|Yes
|No
|[[Fan_Mission_Contests#2011_Halloween_Speed-build_Contest|HSC 11]]
|City Missions
|
|-

|-
!align=left|{{TDM-FM|antr|A Night to Remember}}<br>(v2.1, 2023/05/04)
|DeTeEff (Fieldmedic)
|New → {{Forumlink|https://forums.thedarkmod.com/topic/19452-a-night-to-remember/}} <br>Old → {{Forumlink|https://forums.thedarkmod.com/topic/13177-fan-mission-a-night-to-remember-by-fieldmedic-20111030/}}
|2011-10-31
|33
|No
|Yes
|No
|[[Fan_Mission_Contests#2011_Halloween_Speed-build_Contest|HSC 11]]
|Mansion/Estate <br> Horror
|Ghosts
|-

|-
!align=left|{{TDM-FM|thecreeps|The Creeps}}
|Mortem Desino
|{{Mirrorlink|https://www.gamefront.com/files/20939925/thecreeps.pk4}} {{Forumlink|https://forums.thedarkmod.com/topic/13176-fan-mission-creeps-the-20111030-by-mortem-desino/}}
|2011-10-30
|61
|No
|Yes
|No
|[[Fan_Mission_Contests#2011_Halloween_Speed-build_Contest|HSC 11]]
|Horror
|Ghosts
|-

|-
!align=left|{{TDM-FM|blackbog|House in Blackbog Hollow}}
|Stumpy
|{{Mirrorlink|https://www.bookofages.co.uk/doom3/mods/blackbog.html}} {{Forumlink|https://forums.thedarkmod.com/topic/13172-fan-mission-house-in-blackbog-hollow-by-stumpy-20111028/}}
|2011-10-28
|12
|No
|Yes
|No
|[[Fan_Mission_Contests#2011_Halloween_Speed-build_Contest|HSC 11]]
|Horror
|Spiders, Undead
|-

|-
!align=left|{{TDM-FM|lstl|Let Sleeping Thieves Lie}}
|Sir Taffsalot, Bikerdude
|{{Mirrorlink|https://www.mediafire.com/?zkd1jn4lpwgioh9}} {{Forumlink|https://forums.thedarkmod.com/index.php?/topic/13153-let-sleeping-thieves-lie-by-sir-taffsalot-bikerdude-20102011/}}
|2011-10-20
|13
|No
|Yes
|No
|
|Tombs, Catacombs & Crypts
|Undead
|-

|-
!align=left|{{TDM-FM|samhain|Samhain Night}}<br>(v3.3, 2020/03/02)
|PranQster
|{{Mirrorlink|https://jdchoate.mcn.org/games/darkmod/samhain.zip}} {{Forumlink|https://forums.thedarkmod.com/index.php?/topic/13127-fan-mission-samhain-night-on-bone-hill-by-pranqster-20111009/}}
|2011-10-09
|4.8
|Yes
|Yes
|No
|[[Fan_Mission_Contests#2011_Halloween_Speed-build_Contest|HSC 11]]
|Horror
|Spiders, Undead
|-

|-
!align=left|{{TDM-FM|score_to_settle|A Score to Settle}}
|Springheel
|{{Mirrorlink|https://www.mediafire.com/?f3o7hm4h4ew7o3l}} {{Forumlink|https://forums.thedarkmod.com/index.php?/topic/12894-fan-mission-%2348-a-score-to-settle-by-springheel-20110701/}}
|2011-07-01
|135
|No
|Yes
|No
|[[Fan_Mission_Series#Corbin series|Corbin]]
|City Missions
|
|-

|-
!align=left|{{TDM-FM|siegeshop|Siege Shop}}<br>(v5.0 2020/09/07)
|PranQster and Lowenz
|{{Mirrorlink|https://jdchoate.mcn.org/games/darkmod/siegeshop.pk4}} {{Forumlink|https://forums.thedarkmod.com/index.php?/topic/12874-fan-mission-the-siege-shop-by-pranqster-20110626/}} {{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20559-the-siege-shop-07092020/}}
|2011-06-26
|32.2
|Yes
|Yes
|No
|
|Castle/Fortress
|
|-

|-
!align=left|{{TDM-FM|alberic3|Alberic's Curse}}<br>( v3.11 EFX, 2024/02/23 )
|Bikerdude
|{{Mirrorlink|https://www.gamefront.com/files/20459738/alberic.pk4}} {{Forumlink|https://forums.thedarkmod.com/index.php?/topic/12850-fan-mission-alberics-curse-by-b1k3rdude-20062011/}}
|2011-06-20
|51.6
|Yes
|Yes
|No
|[[Fan_Mission_Contests#2011_Community Seasons Contest|CSC 11]] '''WINNER''' <br> T2 FM homage
|Church/Cathedral
|Spiders, Undead
|-

|-
!align=left|{{TDM-FM|reap|Reap As You Sow}}
|DeTeEff (Fieldmedic)
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/12849-fan-mission-reap-as-you-sow-by-fieldmedic-20110619/}}
|2011-06-19
|52
|No
|Yes
|No
|[[Fan_Mission_Contests#2011_Community Seasons Contest|CSC 11]]
|Outdoor/Daylight <br> Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|rake_off|Rake Off}}
|Jesps
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/12846-fm-rake-off-19-06-2011/}}
|2011-06-19
|8
|No
|Yes
|No
|[[Fan_Mission_Series#Selis Woderose series|Selis Woderose]] <br> [[Fan_Mission_Contests#2011_Community Seasons Contest|CSC 11]]
|Castle/Fortress
|
|-

|-
!align=left|{{TDM-FM|winterharvest|Winter Harvest}}<br>(v2.5 2024/12/15 with Bikerdude)
|ShadowHide
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/12690-seasons-contest-entry-winter-harvest-by-shadowhide/}} '''[https://forums.thedarkmod.com/index.php?/topic/12952-fm-winter-harvest-v2-by-bikerdude-and-shadowhide/ V2]'''
|2011-05-08
|20.2
|Yes
|Yes
|Yes
|[[Fan_Mission_Contests#2011_Community Seasons Contest|CSC 11]]
|Outdoor/Pagan
|Spiders
|-

|-
!align=left|{{TDM-FM|fauchard1_1|Fiasco at Fauchard Street}}
|Melan
|{{Mirrorlink|https://rapidshare.com/files/460141132/fauchard.pk4}} {{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/12655-fan-mission-fiasco-at-fauchard-street-by-melan-20110501//}}
|2011-05-01
|62
|No
|Yes
|No
|[[Fan_Mission_Series#Sir Talbot series|Sir Talbot]]
|Thieves' Highway / Rooftop
|
|-

|-
!align=left|{{TDM-FM|mandrasola|Mandrasola}}
|Sotha
|{{Mirrorlink|https://www.mediafire.com/?2ox2nbhh796ne71}} {{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/12575-fan-mission-mandrasola-by-sotha-20110410/}}
|2011-04-10
|10
|No
|Yes
|Yes
|[[Fan_Mission_Series#Thomas Porter series|Thomas Porter]] <br> [[Fan_Mission_Contests#2011_Community Seasons Contest|CSC 11]]
|City Missions
|Undead
|-

|-
!align=left| Q4 Conversion: Yan's Test
|Bikerdude
|{{Mirrorlink|https://www.moddb.com/mods/the-dark-mod/addons/yantdm1-1}} {{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/12506-fan-mission-q4-map-conversion-yantdm1-280311/}}
|2011-03-28
|28
|No
|No
|No
|
|
|
|-

|-
!align=left|{{TDM-FM|transaction|The Transaction}}
|Sotha
|{{Mirrorlink|https://www.mediafire.com/?ux7mx79wumnvcb6}} {{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/12408-fan-mission-the-transaction-by-sotha-20110304/}}
|2011-03-04
|10
|No
|Yes
|No
|[[Fan_Mission_Series#Thomas Porter series|Thomas Porter]]
|City Missions
|Horror Themes, Undead
|-

|-
!align=left|{{TDM-FM|lockdown1_2_1|Lockdown}}
|GameDevGoro Bikerdude Fidcal
|{{Mirrorlink|https://www.fidcal.com/darkuser/missions/lockdown1_2_1.pk4}} {{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/12064-fm-lockdown-part-1-by-gamedevgoro-and-bikerdude-20101224/}}
|2010-12-25
|3
|No
|Yes
|No
|Lockdown 1
|City Missions
|Undead
|-

|-
!align=left|{{TDM-FM|flakebridge|Flakebridge Monastery}}
|Jesps
|{{Mirrorlink|https://www.file-upload.net/download-3024426/flakebridge.pk4.html}} {{Mirrorlink|https://rapidshare.com/files/434997519/flakebridge.pk4}} {{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/11991-fm-flakebridge-monastery-by-jesps/}}
|2010-12-05
|16
|No
|Yes
|No
|[[Fan_Mission_Series#Selis Woderose series|Selis Woderose]]
|Church/Cathedral
|Undead
|-

|-
!align=left|{{TDM-FM|knighton_manor|Knighton Manor, The}}
|Sotha
|{{Mirrorlink|https://www.mediafire.com/?xrdts3j4t2qxre2}} {{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/11898-fan-mission-the-knighton-manor-by-sotha-20101109/page__view__getnewpost}}
|2010-11-09
|21
|No
|Yes
|No
|[[Fan_Mission_Series#Thomas Porter series|Thomas Porter]]
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|cathedral|St Albans Cathedral}}<br>(v2.0 2014/06/11)
|Bikerdude
|{{Mirrorlink|https://www.filefront.com/17464439/stac141.pk4}}{{Forumlink|1=https://forums.thedarkmod.com/topic/16343-fan-mission-st-albans-cathedral-v20-11062014/}} {{Loot|FM:TDM_St_Alban's_Cathedral_-_Bikerdude}}
|2010-11-01
|67
|No
|Yes
|No
|[[Fan_Mission_Series#St Alban series|St Alban]]
|Church/Cathedral
|Undead
|-

|-
!align=left|{{TDM-FM|swing1_2|Swing}}
|Komag
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/11660-vertigo-contest-entry-swing-by-komag-20100825/}} {{Loot|FM:TDM_Swing_-_Komag}}
|2010-08-25
|3
|No
|Yes
|No
|[[Fan_Mission_Contests#2010 Summer Vertical Contest|SVC 10]]
|Platforming/Jumping <br> Experimental
|
|-

|-
!align=left|{{TDM-FM|caduceus|The Caduceus of St. Alban}}<br>(v.1.5.5 2010/08/26)
|Bikerdude
|{{Mirrorlink|https://www.filefront.com/17237609/stalban.pk4/}}{{Forumlink|https://forums.thedarkmod.com/topic/11644-the-caduceus-of-st-alban-vertical-fm-contest-entry-aug-8th-2010/}}
|2010-08-23
|11.3
|No
|Yes
|No
|[[Fan_Mission_Series#St Alban series|St Alban]] <br> [[Fan_Mission_Contests#2010 Summer Vertical Contest|SVC 10]]
|Church/Cathedral
|Spiders
|-

|-
!align=left|{{TDM-FM|somewhere1_1|Somewhere Above the City}}<br>(v1.1 2010/08/27)
|grayman
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/11619-vertical-contest-mission-somewhere-above-the-city-by-grayman-aug-20-2010/}} {{Loot|FM:TDM_Somewhere_Above_the_City_-_grayman}}
|2010-08-20
|11
|No
|Yes
|Yes
|[[Fan_Mission_Contests#2010 Summer Vertical Contest|SVC 10]]
|Tombs, Catacombs & Crypts
|
|-

|-
!align=left|{{TDM-FM|betrayal|Betrayal}}<br>(v.1.1, 2010/09/01)
|DeTeEff (Fieldmedic)
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/11605-betrayal-by-fieldmedic-20100817-summer-fm-vertical-contest-entry/}} {{Loot|FM:TDM_Awaiting_the_Storm_-_HappyCheeze}}
|2010-08-17
|12
|No
|Yes
|No
|[[Fan_Mission_Contests#2010 Summer Vertical Contest|SVC 10]]
|Horror
|Undead
|-

|-
!align=left|{{TDM-FM|rift|Rift, The}}
|Baddcog
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/11599-vert-contest-mission-the-rift-by-baddcog-aug-15-2010/}}
|2010-08-15
|10
|No
|Yes
|No
|[[Fan_Mission_Contests#2010 Summer Vertical Contest|SVC 10]]
|Lost Civilizations
|Spiders, Undead
|-

|-
!align=left|{{TDM-FM|holetower|Illusionist's Tower}}
|stumpy
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/11541-illusionists-tower-by-stumpy-201085-summer-fm-vertical-contest-entry}} {{Forumlink|1=https://www.bookofages.co.uk/doom3/mods/holetower.html}} {{Loot|FM:TDM_Illusionist%27s_Tower_-_stumpy}}
|2010-08-05
|9
|No
|Yes
|No
|[[Fan_Mission_Contests#2010 Summer Vertical Contest|SVC 10]]
|Horror <br> Experimental
|Spiders, Undead
|-

|-
!align=left|{{TDM-FM|madmountain|Mad's Mountain}}
|Jesps
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/11510-fan-mission-mads-mountain-by-jesps-20100731}} {{Loot|FM:TDM_Lord_Dufford%27s_-_stumpy}}
|2010-07-31
|2
|No
|Yes
|No
|[[Fan_Mission_Contests#2010 Summer Vertical Contest|SVC 10]]
|Outdoor/Caves
|
|-

|-
!align=left|{{TDM-FM|glenham_tower|Glenham Tower, The}}
|Sotha
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/11423-fan-mission-the-glenham-tower-by-sotha-20100717}}
|2010-07-17
|5
|No
|Yes
|No
|[[Fan_Mission_Series#Thomas Porter series|Thomas Porter]] <br> [[Fan_Mission_Contests#2010 Summer Vertical Contest|SVC 10]] '''WINNER'''
|Castle/Fortress <br> Horror
|Undead
|-

|-
!align=left|{{TDM-FM|pandoras_box|Pandora's Box}}
|Jesps, Fidcal
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/11381-fan-mission-pandoras-box-by-jesps20100711}} {{Loot|FM:TDM_Pandora%27s_Box_-_Jesps}}
|2010-07-11
|7
|No
|Yes
|No
|
|Pirate <br> Ship <br> Experimental
|
|-

|-
!align=left|{{TDM-FM|beleaguered_fence|Beleaguered Fence, The}}
|Sotha
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/11298-fan-mission-the-beleaguered-fence-by-sotha-20100623}} {{Loot|FM:TDM_The_Beleaguered_Fence_-_Sotha}}
|2010-06-23
|11
|No
|Yes
|No
|[[Fan_Mission_Series#Thomas Porter series|Thomas Porter]]
|Jail/Prison
|
|-

|-
!align=left|{{TDM-FM|delivery|Special Delivery, A}}
|Silencium18
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/11247-fan-mission-a-special-delivery-by-silencium1820100612}} {{Loot|FM:TDM_A_Special_Delivery_-_Silencium18}}
|2010-06-12
|2
|No
|Yes
|No
|
|Warehouse
|
|-

|-
!align=left|{{TDM-FM|alchemist|Alchemist, The}}<br>(2010/06/04)
|Sotha, Fidcal
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/11170-fan-mission-the-alchemist-by-sotha-fidcal20100601}} {{Loot|FM:TDM_The_Alchemist_-_Sotha_%26_Fidcal}}
|2010-06-01
|27
|No
|Yes
|No
|[[Fan_Mission_Series#Thief's Den series|Thief's Den]]
|City Missions
|Undead
|-

|-
!align=left|{{TDM-FM|storm|Awaiting The Storm}}
|HappyCheeze
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/11095-fm-awaiting-the-storm-by-happycheeze-20200522}} {{Loot|FM:TDM_Awaiting_the_Storm_-_HappyCheeze}}
|2010-05-22
|4
|No
|Yes
|No
|
|City Missions
|
|-

|-
!align=left|{{TDM-FM|sound_alert_trainer|Sound Alert & Blackjack Trainer}}
|Dark Mod Team
|
|2010-05-14
|0.2
|No
|No
|No
|
|Training
|
|-

|-
!align=left|{{TDM-FM|nhat3|No Honor Among Thieves}}<br>(v.4.3 EFX, Subtitles, Water Effects 2024/02/23)
|Goldchocobo, RailGun, Mortem Desino, Bikerdude
|{{Mirrorlink|https://tinyurl.com/2a9mdcs}}{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/10993-fan-mission-no-honor-among-thieves-20100429}} {{Loot|FM:TDM_No_Honor_Among_Thieves_-_Goldchocobo}}
|2010-04-29
|229.8
|Yes
|Yes
|Yes
|
|Church/Cathedral; City Missions; Outdoor/Pagan, Mansion/Estate
|Spiders, Undead
|-

|-
!align=left|{{TDM-FM|heartv2|Heart of Lone Salvation, The}}<br>(v.2.0, 2014/04/12)
|Fidcal, Baddcog, Bikerdude
|{{Forumlink|1=https://forums.thedarkmod.com/topic/10878-fan-mission-the-heart-of-lone-salvation-by-fidcal-baddcog-bikerdude-20100402/?p=213506}} {{Walkthrough|FM:TDM_The_Heart_of_Lone_Salvation_-_Fidcal_%26_Baddcog_%26_Bikerdude}} {{loot|FM:TDM_The_Heart_of_Lone_Salvation_-_Fidcal_%26_Baddcog_%26_Bikerdude}}
|2010-04-02
|41
|No
|Yes
|No
|[[Fan_Mission_Series#Thief's Den series|Thief's Den]]
|City Missions
|Spiders
|-

|-
!align=left|{{TDM-FM|dufford|Lord Dufford's}}
|stumpy
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/10868-fan-mission-lord-duffords-20100331}} {{Loot|FM:TDM_Lord_Dufford%27s_-_stumpy}}
|2010-03-31
|22
|No
|Yes
|No
|
|City Missions
|
|-

|-
!align=left|{{TDM-FM|builders_influence|Builder's Influence, The}}<br>(2010/03/23)
|Railgun, Springheel
|{{Mirrorlink|https://www.fidcal.com/darkuser/missions/builders_influence.pk4}}{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/10811-fan-mission-the-builders-influence-20100320/}} {{Loot|FM:TDM_The_Builders_Influence_-_Railgun%26Springheel}}
|2010-03-20
|15
|No
|Yes
|No
|[[Fan_Mission_Series#Corbin series|Corbin]]
|Castle/Fortress
|
|-

|-
!align=left|{{TDM-FM|business3|Business as Usual}}<br>(v3.0 2013/01/19)
|Bikerdude
|{{Mirrorlink|1=https://rapidshare.com/files/335299431/business.pk4.html}}{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/10533-fan-mission-business-as-usual-by-b1k3rdude-14012010-christmas-fm-contest-entry/page__view__findpost__p__207055}}{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/14450-fan-mission-business-as-usual-v30-20130119/}}
|2010-01-14
|16.1
|No
|Yes
|No
|[[Fan_Mission_Contests#2009 Grand Christmas Contest|GCC 09]]
|Sewers
|
|-

|-
!align=left|{{TDM-FM|returntothecity|Return to the City}}<br>(v3.0 2015/01/03)
|Melan, Bikerdude
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/10509-fan-mission-return-to-the-city-by-melan-20100110/}} {{Forumlink|1=https://www.ttlg.com/forums/showthread.php?t=130519/}} {{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/12390-fan-mission-return-to-the-city-v2-01032011/}}
|2010-01-10
|26
|No
|Yes
|No
|[[Fan_Mission_Series#Sir Talbot series|Sir Talbot]] <br> [[Fan_Mission_Contests#2009 Grand Christmas Contest|GCC 09]] '''WINNER'''
|City Missions
|
|-

|-
!align=left|{{TDM-FM|sons_of_baltona_1|Sons of Baltona 1, The}}
|Carnage
|{{Mirrorlink|1=https://www.mediafire.com/?m4ywobjodm0}}{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/10498-fan-mission-the-sons-of-baltona-1-by-carnage-20100109}}
|2010-01-09
|3
|No
|Yes
|No
|[[Fan_Mission_Contests#2009 Grand Christmas Contest|GCC 09]] / Baltona 1
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|living_expenses|Living Expenses}}
|Sonosuke
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/10451-fm-living-expenses-by-sonosuke-2-jan-10/page__view__findpost__p__205386}}
|2010-01-02
|6
|No
|Yes
|No
|[[Fan_Mission_Contests#2009 Grand Christmas Contest|GCC 09]]
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|trapped|Trapped!}}
|RailGun
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/10442-fm-trapped-by-railgun-dec-30/page__view__findpost__p__205092}}
|2009-12-30
|6
|No
|Yes
|No
|
|Jail/Prison
|
|-

|-
!align=left|{{TDM-FM|parcel|Parcel, The}}
|Xonze
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/10404-fm-the-parcel-by-xonze-dec-24/page__view__findpost__p__204459}}
|2009-12-24
|7
|No
|Yes
|No
|[[Fan_Mission_Contests#2009 Grand Christmas Contest|GCC 09]]
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|too_late|Too Late}}
|Nielsen74
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/10400-fm-too-late-by-nielsen74-24-dec-09/page__view__findpost__p__204396}}
|2009-12-24
|4
|No
|Yes
|No
|[[Fan_Mission_Contests#2009 Grand Christmas Contest|GCC 09]]
|Warehouse
|
|-

|-
!align=left|{{TDM-FM|thieves|Thieves}}
|Silencium, RailGun, Fidcal
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/10286-fm-the-thieves-nov-2509/}}
|2009-11-26
|9
|No <br> [https://www.moddb.com/mods/the-dark-mod/addons/unofficial-thieves-efx Unofficial EFX Build]
|Yes
|No
|
|City Missions
|
|-

|-
!align=left|{{TDM-FM|patently_dangerous|Patently Dangerous}}<br>(v.2.0 EFX, 2021/01/03)
|demagogue
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/10125-fm-patently-dangerous-oct3109/page__view__findpost__p__199324/}}
|2009-10-31
|22.5
|Yes
|Yes
|No
|
|City Missions
|
|-

|-
!align=left|{{TDM-FM||Dark Mod Training Mission, The}}
|TDM Team
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/9932-fm-training-mission-17-oct-09/}}
|2009-10-17
|6
|Yes ( 2.13 beta )
|
|No
|[[Fan_Mission_Series#Introduction_campaign|Official Campaign]]
|Training <br> Platforming/Jumping
|
|-

|-
!align=left|{{TDM-FM|crown_of_penitence|Crown of Penitence, The}}
|Jesps
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/9934-fm-crown-of-penitence-by-jesps-17-oct-09/}}
|2009-10-16
|12
|No
|Yes
|No
|
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|chalice1_1|Chalice of Kings, The}}<br>(v.2.0, 2015/09/24) (Bikerdude and Xarg)
|Fidcal
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/9935-fm-chalice-of-kings-by-fidcal-17-oct-09/}} {{Loot|FM:TDM_Chalice_of_Kings_-_Fidcal}}
|2009-10-15
|3
|No
|Yes
|No
|[[Fan_Mission_Series#Thief's Den series|Thief's Den]]
|Castle/Fortress
|
|-

|-
!align=left|{{TDM-FM|outpost|Outpost, The}}
|angua, greebo
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/9937-fm-the-outpost-by-angua-greebo-17-oct-09/}}
|2008-12-23
|2
|No
|Yes
|No
|
|Castle/Fortress
|
|-

|-
!align=left|{{TDM-FM||Mission 2: Tears of Saint Lucia, The}}<br>(v.3.0, 2017/02/14)
|TDM Team
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/10579-fan-mission-the-tears-of-st-lucia-20081021/page__view__findpost__p__207972}} {{Loot|FM:TDM_The_Tears_of_Saint_Lucia_-_jdude}} [https://www.youtube.com/watch?v=yrGxoi3LSGg Briefing]
|2008-10-21
|20.3
|Yes (2.11)
|
|Yes
|[[Fan_Mission_Series#Introduction_campaign|Official Campaign]]
|Church/Cathedral
|Spiders
|-

|-
!align=left|{{TDM-FM|closemouthed_shadows|Closemouthed Shadows}}<br>(v.2.0, 2012/01/15)
|LordSavage, Bikerdude
|{{Forumlink|1=https://forums.thedarkmod.com/topic/13383-fan-mission-closemouthed-shadows-2008-reworked-for-tdm-107-20120115/}}
|2008-09-21
|2
|No
|Yes
|No
|Closemouthed Shadows 1
|Mansion/Estate
|
|-

|-
!align=left|{{TDM-FM|thiefsden|Thief's Den}}<br>(v.2.0, 2010/07/04)
|Fidcal, greebo
|{{Forumlink|1=https://forums.thedarkmod.com/index.php?/topic/11347-fan-mission-thiefs-den-re-release-by-fidcal20100704}} {{Walkthrough|FM:TDM_Thief's_Den_-_Fidcal}} {{Loot|FM:TDM_Thief%27s_Den_-_Fidcal}}
|2008-01-18
|3
|No
|Yes
|No
|[[Fan_Mission_Series#Thief's Den series|Thief's Den]]
|City Missions
|
|}

To see a speculative list of Upcoming Fan Missions, please visit: [[Upcoming Fan Missions]]

== Table notes ==

'''Links Key'''
{|class="wikitable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2
|-
|[https://wiki.thedarkmod.com/images/b/be/Icon_forum.png https://wiki.thedarkmod.com/images/b/be/Icon_forum.png]
|Link to discussion in Forums
|-
|{{Mirrorlink|}}
|Misc. download mirror
|-
|{{Loot|}}
|Loot list
|-
|{{Walkthrough|}}
|Walkthrough
|}

----

'''Mission Type Key'''

''Bear in mind that individual FMs can have combinations of two or three of these overarching genres/themes, rather than just a single one.''

{|class="wikitable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2
|-
|'''''Bank Jobs'''''
|Fan mission involving a heist or other thievy action inside a local banking institution. Will often contain the outsmarting of security systems, gaining access to a safe and cracking its code.
|-
|'''''Castle/Fortress'''''
|Fan mission involving a heist or other thievy action inside or outside a castle or fortress, either one that serves as a military garrison, or as someone's private residence. Frequently involves background characters from the nobility.
|-
|'''''City Missions'''''
|Fan mission that is set mainly in the streets and public spaces of an urban area, such as a town or city. Though the player is most often out on the streets, these missions tend to also involve some degree of exploration and infiltration into private and public buildings alike.
|-
|'''''Church/Cathedral'''''
|Fan mission set in and around religious buildings and institutions, such as churches, monasteries, cathedrals, church bureaus, church workshops, etc. Frequently involves [[Clergy/Builder_Characters|ecclesiastical characters]] from the TDM setting's [[Builders|Builder Church]].
|-
|'''''Experimental'''''
|Fan mission which involves some creative design or gameplay element that isn't typical for the vast majority of TDM missions. FMs set in highly unusual environments, or with a puzzle-like nature, can fit under this label.
|-
|'''''Inn/Tavern'''''
|Fan mission set mostly in and around an inn, tavern or shanty. Usually focused on robbing some rich guest, acquiring an item stored by the guest at the inn, or gathering intel at the inn.
|-
|'''''Jail/Prison'''''
|Fan mission involving an escape from a prison (by the imprisoned player character), infiltration of a prison to gather intel from inmates or help an inmate escape the prison, etc.
|-
|'''''Lost Civilizations'''''
|Fan mission focused on the exploration of ancient ruins, whether above ground or in deep subterranean caverns. Can often overlap with the ''Horror'' or ''Tombs, Catacombs & Crypts'' type of mission, but not necessarily.
|-
|'''''Horror'''''
|Fan mission with an overt horror theme. Depending on the author's approach and intentions, it can focus on psychological horror, or horror based on danger from supernatural threats, or varying combinations of both.
|-
|'''''Mansion/Estate'''''
|Fan mission involving a heist or other thievy action inside someone's private residence (a fancy house, a manor house) and its surrounding grounds. Frequently involves background characters from the nobility or the more affluent townsmen or citizens.
|-
|'''''Museum Heists'''''
|Fan mission focusing on a heist in a museum, art gallery or other institution storing priceless artefacts, artworks, gemstone collections, etc.
|-
|'''''Outdoor/Forest'''''
|Fan mission set in a mostly natural outdoor environment, involving the exploration of forested areas and woodland. Can overlap with other Outdoor style missions.
|-
|'''''Outdoor/Caves'''''
|Fan mission set in a mostly natural outdoor environment, but involving the exploration of natural caves and caverns. Can overlap with other Outdoor style missions.
|-
|'''''Outdoor/Daylight'''''
|Fan mission set in a mostly outdoor environment, during the daytime (in contrast to the usual TDM missions, set at night time or early dusk). Can overlap with other Outdoor style missions.
|-
|'''''Outdoor/Pagan'''''
|Fan mission set in a mostly natural outdoor environment, involving some presence of [[Pagans|pagan tribes]] from TDM's setting. Perhaps even pagan camps and settlements. Can overlap with other Outdoor style missions.
|-
|'''''Pirate'''''
|Fan mission involving the presence of characters engaging in piracy or smuggling, and various related piratical themes. Can overlap with the ''Ship'' type of mission, but not necessarily.
|-
|'''''Platforming/Jumping'''''
|Fan mission focusing on testing the player's movement, jumping and climbing skills, with or without equipment.
|-
|'''''Sewers'''''
|Fan mission which involves the use of the city sewers or others sewers in some way, often as a stealthy means of entry or escape.
|-
|'''''Ship'''''
|Fan mission which takes place aboard a vessel, in port or at sea, or otherwise involves ships to a great degree. Can overlap with the ''Pirate'' type of mission, but not necessarily.
|-
|'''''Thieves' Highway / Rooftop'''''
|Fan mission involving a lot of movement and travel on the rooftops of a town or city (colloquially "The Thieves' Highway").
|-
|'''''Tombs, Catacombs & Crypts'''''
|Fan mission involving the exploration of old tombs, catacombs and crypts, often for the purposes of treasure and artefact hunting. Can often overlap with the ''Horror'' or ''Lost Civilizations'' type of mission, but not necessarily.
|-
|'''''Train'''''
|Fan mission which takes place aboard a train, either one already underway or one waiting at a station. Given TDM's setting, most likely a train with an early steam locomotive.
|-
|'''''Training'''''
|Fan mission label that is unique to the official Training Mission, an open-ended tutorial mission where players can practice and test their TDM gameplay skills at their own leisure, and to the smaller blackjacking-trainer FM, which focuses on practicing NPC knockouts by the player.
|-
|'''''Warehouse'''''
|Fan mission which takes place in and around a warehouse, usually in some industrial area of a city, or at a port.
|}

----

'''Contest Key'''

GCC 09: [[Fan_Mission_Contests#2009 Grand Christmas Contest|Grand Christmas Contest 2009]]

SVC 10: [[Fan_Mission_Contests#2010 Summer Vertical Contest|Summer Vertical Contest 2010]]

CSC 11: [[Fan_Mission_Contests#2011 Community Seasons Contest|Community Seasons Contest 2011]]

HSC 11: [[Fan_Mission_Contests#2011 Halloween Speed-build Contest|Halloween Speed-Build Contest 2011]]

CBC 12: [[Fan_Mission_Contests#2012 Community Beginner Contest|Community Beginner Contest 2012]]

CUC 13: [[Fan_Mission_Contests#2013 Community Unusual Contest|Community Unusual Contest 2013]]

HSC 14: [[Fan_Mission_Contests#2014 Halloween Speed-build Contest|Halloween Speed-Build Contest 2014]]

HSC 15: [[Fan_Mission_Contests#2015 Halloween Speed-build Contest|Halloween Speed-Build Contest 2015]]

CCC 22: [[Fan_Mission_Contests#2022_Christmas_Connection_Contest|Christmas Connections Contest 2022]]

15YR: [[Fan_Mission_Contests#2024_15th_Anniversary_Contest|15th Anniversary Contest (2024)]]

----

== Editing this table ==
* Please only include playable missions that are fully released, not those currently in development or testing. Tutorials, demos, prefabs, etc. should be listed elsewhere.
* A mission title may be listed in plain text as a record of release, or preferably a link to an information page or primary direct download.
* List by release date descending (newest at the top).
* If a fan mission only has a single mirror/host please consider adding additional mirrors.

== See also ==
* [https://wiki.thedarkmod.com/index.php?title=Category:Official_FMs Fan missions] - An index of fan mission pages on this wiki.
* [https://wiki.thedarkmod.com/index.php?title=Category:Official_missions_(OMs) Official missions] - An index of Oficial mission pages on this wiki.
* [[Fan Mission Series]] - An overview of all currently known series or campaigns of fan missions interconnected by their stories or characters. There are already plenty in TDM, and have been since its early days as an expandable game.
* [[Mission recommendation discussions]] - An overview of past discussions on what FMs the community recommends to players looking for various challenges (difficulty, size, theme, setting, objectives, etc.).
* [[Fan Mission Contests]] - An overview of past and present contests in Fan Mission creation, by members of the TDM community.
* [[Upcoming Fan Missions]] - An overview of Fan Missions in development or tentatively planned. (''Do not'' edit the overview.)
* [https://tdmdb.com/missions tdmdb.com] An external TDM mission database, which data is partly coming from this wiki page.

{{general|sort=Fan Missions}}
[[Category:Fan Missions]]
[[Category:Official FMs| ]]

Conversation Tutorial

2025-06-13T20:45:48Z

Frost Salamander: /* Conversation Editor window */

Presumably your AI are pathing along, minding their own business, when you want them to interact, say something specific, or glance at one another. Here's how to set that up, step by step... ([[Conversations]] are more than just talk, they may control movement, animations, or other things.)

= Triggering =
First they have to run into a [[Triggers|trigger]] to initiate a "conversation", either as the target of a [[Path Nodes|path node]] (as of TDM 2.02), another trigger entity, a stim/response trigger, or equivalent.

The trigger targets an "atdm:target_startconversation" entity (found in targets folder). That entity gets the spawnarg "conversation" "whatever" (substitute "whatever" with a label to identify this conversation compared to future ones in the list).

[[File:Conversation Start Setup.png|large|center]]
'''Make sure to use the actual conversation as the value for "conversation", NOT the entity itself! In this example the correct value for the conversation start is "lost_key", NOT "convo_kitchen".'''

=Sounds/Lines=
Before you jump in, you will need to type in which soundshaders you will be using if you want them to talk. So if you haven't already picked your lines, pop in a temporary Speaker and get the names of the [[Sound_Folder_Structure|soundshaders]] you'll want to use.

For example, I have an AI greet a horse with "tdm_ai_wench_greet_civilian_to_civilian", to which the horse whinnies via "animal_horse_idle", then she commiserates to it from, "tdm_ai_wench_idle". If you desire a specific line, or custom, you'll have to create your own soundshader (a text file listing an audiofile).

An audiofile (e.g., .ogg file) intended for use in a conversation should be mono, not stereo. Stereo will play, but AI lip-sync will lag.

=Conversation Editor window=
Now enter the Conversation Editor (map menu), which will create an entity if you don't already have one. Be sure it's not placed in the void!

Click +Add down at the bottom to create a new conversation, then edit it. You'll notice toward the top, "Actors must be within talk distance" and "always facing". These cause them to move toward each other, and/or turn when the conversation is triggered, not that the conversation waits until they are in range. For each actor (whether you have just one, or multiple AI interacting), +Add that actor and enter their '''entity name'''. Names identify who does what and when in the next step.

Now in the bottom you may add commands, which run in sequence (generally). You may choose for one to not wait, in which case the next will occur perhaps before the current completes. This can be good to have AI talk more naturally overlapping, rather than a lengthy pause between each spoken line.

Typical commands are "Talk" to say something (paste in a soundshader name you noted earlier), look at something or someone (including player1), wait a few seconds, etc. For example, my wench looks at the horse, says her line, the horse whinnies in reply, then she delivers her final line. That's it, now check to see how it works out in game.

(Note: if you want to mute your AI generally, so they don't use their usual vocalizations the rest of the time (perhaps not making sense leading in or out of your conversation), change "def_vocal_set" to "atdm:ai_vocal_set_mute".)

=See also=
[[Conversations]]

[[Cutscenes Part 3: Lighting, Placing the Player, and Conversations#Conversations]]

[[Category:Tutorial]]
[[Category:AI]]
[[Category:AI Tutorials]]

User:Frost Salamander

2025-05-21T19:06:32Z

Frost Salamander: /* Create an inventory icon for an existing model from a DR screenshot */

== TDM Files and Contents ==

{| class="wikitable"
|+ Caption text
|-
! Content !! File path !! Notes
|-
| Skins || tdm_models_decls01.pk4\skins || skin files shipped with TDM
|-
| Script Constants|| tdm_base01.pk4\script\tdm_defs.script || constant values. Useful if you need to know the literal values for use in your scripts.
|-
| Script Objects|| tdm_base01.pk4\script || various script objects for entities.
|-
| tdm_ai_humanoid_newskel.def || tdm_ai_humanoid_undead01.pk4\def\tdm_ai_humanoid_newskel.def || Base class for all TDM humanoid entities
|-
| GUI Icons || tdm_gui01.pk4\dds\guis\assets\hud\ || HUD icons. e.g. loot, potions, etc
|-
| sound shaders || tdm_sound_ambient_decls01.pk4\sound || ambient environmental sound shaders
|-
| materials definitions || tdm_textures_base01.pk4\materials || base materials files
|-
| guard model materials || tdm_ai_humanoid_guards01.pk4 || guard materials and texture files
|-
| Stim types || tdm_base01.pk4/script/tdm_stim_response.script ||
|-
| Readable textures || tdm_gui01.pk4/dds/guis/assets/readables || various parchment textures
|-
| Blueprint textures || tdm_models02.pk4 || textures/readables/blueprint01*
|-
| Light textures || tdm_textures_base01.pk4 || In both /lights and textures/lights
|}

== Creating an Image Decal with Gimp ==
# Go to somewhere like pixabay.com and search for free images. I usually filter by 'vector graphics' (e.g. PNG) because it supports alpha channel which you'll need for decals.
# Once you find an image, download it. I tend to get medium-sized versions (e.g. close to 1024 x 1024)
# Open the file in Gimp
# Scale the image to 1024x1024 pixels.
# export as TGA

== Creating a Text Decal with Gimp ==
# Open Gimp - New ->
# Set image size to 1024 x 1024 (or something more rectangular like 1024 x 512)
# Click Advanced -> Fill with: transparency
# Add text layer
# When happy with text, right-click the text layer and 'merge down' into alpha layer
# save and export as TGA.
# Create a materials file (.mtr) like so:

textures/darkmod/decals/signs/coronet
{
DECAL_MACRO
noimpact

{
blend blend
map textures/darkmod/decals/signs/coronet
}
}

== Create an inventory icon for an existing model from a DR screenshot ==
# In DarkRadiant, right-click and choose 'Create Model...' and choose the object you wish to use.
# in the preview window with the model showing, take a screenshot selection using something like the Windows Snipping Tool. Leave a centimeter or so of grey color around the object so that the in-game icon doesn't touch the text. Additionally, make sure the screenshot is square-shaped as we will be resizing the image to 128x128 pixels.
# Save the screenshot as a JPEG somewhere on your local disk.
# Open the file with GIMP.
# From the menu, choose Layer -> Transparency -> Color to Alpha...
# A pop up will appear. Next to the Color bar there will be an eye dropper icon. This is the color picker.
# Click the color picker and then click the grey area that surrounds your image. Don't worry if it looks like it's already been converted to alpha (the grey squares). The grey squares should turn a lighter colour.
# Click OK
# TIP: If the image becomes transparent as well, this is because its color is not far off from the grey background. Reduce the 'Opacity Threshold' until the checkerboard pattern doesn't cover your image (try 0.1).
# Resize the image by clicking Image -> Scale Image... Make it 128 x 128 pixels. Click 'Scale'
# Export as DDS by clicking File -> Export As... and type a file name that ends in .dds. Choose BC3 / DXT5 compression and don't bother with mipmaps.
# Add the .dds file to your FM folder under 'dds\guis\assets\hud\inventory_icons' if you want them to be in the same folder as the stock icons.

== Creating a material using existing images (e.g. from textures.com) using GIMP ==

'''Written on May 28th, 2023 using GIMP 2.10.34'''

This will describe how to create your own texture (material) using an image found on the internet. I will use textures.com as an example.

'''Ensure that the license for whatever source you use is appropriate for TDM (e.g. allows use in video games)'''

We will end up with 3 image files and one materials file:
* diffuse map (the base image with colour details, etc)
* normal map (faked bump/dent data)
* DarkRadiant editor icon

This doesn't cover creation of a specular map. This isn't needed unless your material needs a shiny surface (e.g. metal or wet surfaces).

=== Obtain your image ===
# Log into textures.com and find an image you like under the 'Regular Photos' section ('''NOT''' 'Special Content'). Make sure it's seamless if it needs to be tiled/repeatable (e.g. for bricks or walls). If it's something like a door or window, it doesn't need to be seamless. There is normally a JPG format that that is close to or exactly 1024x1024 pixels. Download it.

=== Open your Image in GIMP ===
The first thing you may see here is a pop-up asking if you want to convert the image to 'the built-in sRGB color profile'. I'm not sure the implications of doing this but just choose 'Convert'. '''(ADVICE NEEDED)'''

=== Resize Image (if needed) ===
TDM standard resolution for textures is 1024 x 1024. However it's possible to get away with 2048 x 2048 at the cost of file size and performance.
If you can't find a 1024 x 1024 image for whatever reason (say it's 4K instead), you can scale it down:
# With the image open in GIMP, click Image -> Scale Image...
# Set the width in 'Image Size' in pixels to 1024. Make sure the width and height are 'chained' (the little link icon should be whole). The height will then scale down proportionately to match the width.

=== Crop your Image ===
This is only needed if you don't intend to use the entire image as-is (e.g. if you want to cut a door or window out of an image). Skip this section if that is not the case.
# With the image in GIMP, select the Crop Tool (Shift+C).
# Under the 'Tool Options' tab, tick the box for 'Delete cropped pixels'
# Using the crop tool select the area you want to keep on the image with your mouse, and press 'Enter' when done.

=== Create the Diffuse Map (DDS File) ===
# With the original or cropped image open in GIMP Choose File -> Export as...
# In the next popup, change the filename to 'texturename.dds' and click 'Export'.
# On the next pop-up, choose your compression format (see below) and select 'Generate mipmaps'. Under 'Mipmap Options' choose 'Filter': 'Kaiser' for best quality. Click 'Export'
- Compression:
- if your image contains an alpha channel, choose 'BC3 / DXT5'
- if your image does not contain an alpha channel, choose 'BC1 / DXT1'

=== Create the Normal Map (TGA File)===
Apart from creating the normal map, the point of the first few steps is to reduce the amount of 'noise' in the image which can lead to a grainy appearance.
# With the original or cropped image open in GIMP, select Colors -> Desaturate -> Desaturate. Click 'OK'
# Select Filters -> Blur -> Gaussian Blur. Leave the defaults and click 'OK'.
# Select Colors -> Curves and adjust the curve to 'wash out' (i.e. brighten) the image to remove any noise detail.
# Select Filters -> Generic -> Normal Map..
# The image will change to a blueish colour and you will be able to see the 'bumps'. The only thing I adjust here is the 'Scale' property. If it looks very grainy, just reduce the scale. For things like bricks, I use a value < 5 or else the finished texture will look very grainy in TDM. For stuff like doors, a value of about 10 looks OK.
# After adjusting the scale, click 'OK'
# Choose File -> Export as..., change the file name to 'texturename_local.tga' and click 'Export'
# On the next pop-up, untick 'RLE compression' and leave 'Origin' at 'Bottom left'. Click 'Export'. '''(ADVICE NEEDED)'''

=== Create the editor icon (JPG File) ===
# Since you've modified the image, either close and re-open the image in GIMP, or go back into your Undo History and select the original image (or cropped image if it's been cropped).
# Choose Image -> Scale Image... from the menu.
# On the dialogue, either scale it to 256x256 px (if it was a 1024x1024 image originally), or just scale it down to 25% if it was something else. Click 'Scale'. If the image looks too blurry, you can try 512 x 512.
# Choose File -> Export as..., change the file name to 'texturename_ed.jpg' and click 'Export'
# On the next pop-up, untick all the 'save data' boxes except for 'Save color profile' '''(ADVICE NEEDED)'''. Click 'Export'

=== Create TDM materials file ===
# Within your FM folder, save all your images in the appropriate TDM folder structure. Just follow the existing conventions. For example your DDS files go into 'dds/textures/darkmod/stone/brick' and your normal map and editor files go into 'textures/darkmod/stone/brick'
# Create the materials file as follows below. Give it a name like 'mybricks.mtr' and put it in the /materials folder in your FM. The material name as it appears in DarkRadiant appears at the top.

'''NOTE''': 'texturename' in this example is 'bricks_dirty'
textures/darkmod/stone/brick/bricks_dirty
{
stone
description "vine_friendly"

qer_editorimage textures/darkmod/stone/brick/bricks_dirty_ed
diffusemap textures/darkmod/stone/brick/bricks_dirty
bumpmap textures/darkmod/stone/brick/bricks_dirty_local
}

User:Frost Salamander

2025-05-21T19:06:18Z

Frost Salamander: /* Create an inventory icon for an existing model from a DR screenshot */

== TDM Files and Contents ==

{| class="wikitable"
|+ Caption text
|-
! Content !! File path !! Notes
|-
| Skins || tdm_models_decls01.pk4\skins || skin files shipped with TDM
|-
| Script Constants|| tdm_base01.pk4\script\tdm_defs.script || constant values. Useful if you need to know the literal values for use in your scripts.
|-
| Script Objects|| tdm_base01.pk4\script || various script objects for entities.
|-
| tdm_ai_humanoid_newskel.def || tdm_ai_humanoid_undead01.pk4\def\tdm_ai_humanoid_newskel.def || Base class for all TDM humanoid entities
|-
| GUI Icons || tdm_gui01.pk4\dds\guis\assets\hud\ || HUD icons. e.g. loot, potions, etc
|-
| sound shaders || tdm_sound_ambient_decls01.pk4\sound || ambient environmental sound shaders
|-
| materials definitions || tdm_textures_base01.pk4\materials || base materials files
|-
| guard model materials || tdm_ai_humanoid_guards01.pk4 || guard materials and texture files
|-
| Stim types || tdm_base01.pk4/script/tdm_stim_response.script ||
|-
| Readable textures || tdm_gui01.pk4/dds/guis/assets/readables || various parchment textures
|-
| Blueprint textures || tdm_models02.pk4 || textures/readables/blueprint01*
|-
| Light textures || tdm_textures_base01.pk4 || In both /lights and textures/lights
|}

== Creating an Image Decal with Gimp ==
# Go to somewhere like pixabay.com and search for free images. I usually filter by 'vector graphics' (e.g. PNG) because it supports alpha channel which you'll need for decals.
# Once you find an image, download it. I tend to get medium-sized versions (e.g. close to 1024 x 1024)
# Open the file in Gimp
# Scale the image to 1024x1024 pixels.
# export as TGA

== Creating a Text Decal with Gimp ==
# Open Gimp - New ->
# Set image size to 1024 x 1024 (or something more rectangular like 1024 x 512)
# Click Advanced -> Fill with: transparency
# Add text layer
# When happy with text, right-click the text layer and 'merge down' into alpha layer
# save and export as TGA.
# Create a materials file (.mtr) like so:

textures/darkmod/decals/signs/coronet
{
DECAL_MACRO
noimpact

{
blend blend
map textures/darkmod/decals/signs/coronet
}
}

== Create an inventory icon for an existing model from a DR screenshot ==
# In DarkRadiant, right-click and choose 'Create Entity...' or 'Create Model...' and choose the object you wish to use.
# in the preview window with the model showing, take a screenshot selection using something like the Windows Snipping Tool. Leave a centimeter or so of grey color around the object so that the in-game icon doesn't touch the text. Additionally, make sure the screenshot is square-shaped as we will be resizing the image to 128x128 pixels.
# Save the screenshot as a JPEG somewhere on your local disk.
# Open the file with GIMP.
# From the menu, choose Layer -> Transparency -> Color to Alpha...
# A pop up will appear. Next to the Color bar there will be an eye dropper icon. This is the color picker.
# Click the color picker and then click the grey area that surrounds your image. Don't worry if it looks like it's already been converted to alpha (the grey squares). The grey squares should turn a lighter colour.
# Click OK
# TIP: If the image becomes transparent as well, this is because its color is not far off from the grey background. Reduce the 'Opacity Threshold' until the checkerboard pattern doesn't cover your image (try 0.1).
# Resize the image by clicking Image -> Scale Image... Make it 128 x 128 pixels. Click 'Scale'
# Export as DDS by clicking File -> Export As... and type a file name that ends in .dds. Choose BC3 / DXT5 compression and don't bother with mipmaps.
# Add the .dds file to your FM folder under 'dds\guis\assets\hud\inventory_icons' if you want them to be in the same folder as the stock icons.

== Creating a material using existing images (e.g. from textures.com) using GIMP ==

'''Written on May 28th, 2023 using GIMP 2.10.34'''

This will describe how to create your own texture (material) using an image found on the internet. I will use textures.com as an example.

'''Ensure that the license for whatever source you use is appropriate for TDM (e.g. allows use in video games)'''

We will end up with 3 image files and one materials file:
* diffuse map (the base image with colour details, etc)
* normal map (faked bump/dent data)
* DarkRadiant editor icon

This doesn't cover creation of a specular map. This isn't needed unless your material needs a shiny surface (e.g. metal or wet surfaces).

=== Obtain your image ===
# Log into textures.com and find an image you like under the 'Regular Photos' section ('''NOT''' 'Special Content'). Make sure it's seamless if it needs to be tiled/repeatable (e.g. for bricks or walls). If it's something like a door or window, it doesn't need to be seamless. There is normally a JPG format that that is close to or exactly 1024x1024 pixels. Download it.

=== Open your Image in GIMP ===
The first thing you may see here is a pop-up asking if you want to convert the image to 'the built-in sRGB color profile'. I'm not sure the implications of doing this but just choose 'Convert'. '''(ADVICE NEEDED)'''

=== Resize Image (if needed) ===
TDM standard resolution for textures is 1024 x 1024. However it's possible to get away with 2048 x 2048 at the cost of file size and performance.
If you can't find a 1024 x 1024 image for whatever reason (say it's 4K instead), you can scale it down:
# With the image open in GIMP, click Image -> Scale Image...
# Set the width in 'Image Size' in pixels to 1024. Make sure the width and height are 'chained' (the little link icon should be whole). The height will then scale down proportionately to match the width.

=== Crop your Image ===
This is only needed if you don't intend to use the entire image as-is (e.g. if you want to cut a door or window out of an image). Skip this section if that is not the case.
# With the image in GIMP, select the Crop Tool (Shift+C).
# Under the 'Tool Options' tab, tick the box for 'Delete cropped pixels'
# Using the crop tool select the area you want to keep on the image with your mouse, and press 'Enter' when done.

=== Create the Diffuse Map (DDS File) ===
# With the original or cropped image open in GIMP Choose File -> Export as...
# In the next popup, change the filename to 'texturename.dds' and click 'Export'.
# On the next pop-up, choose your compression format (see below) and select 'Generate mipmaps'. Under 'Mipmap Options' choose 'Filter': 'Kaiser' for best quality. Click 'Export'
- Compression:
- if your image contains an alpha channel, choose 'BC3 / DXT5'
- if your image does not contain an alpha channel, choose 'BC1 / DXT1'

=== Create the Normal Map (TGA File)===
Apart from creating the normal map, the point of the first few steps is to reduce the amount of 'noise' in the image which can lead to a grainy appearance.
# With the original or cropped image open in GIMP, select Colors -> Desaturate -> Desaturate. Click 'OK'
# Select Filters -> Blur -> Gaussian Blur. Leave the defaults and click 'OK'.
# Select Colors -> Curves and adjust the curve to 'wash out' (i.e. brighten) the image to remove any noise detail.
# Select Filters -> Generic -> Normal Map..
# The image will change to a blueish colour and you will be able to see the 'bumps'. The only thing I adjust here is the 'Scale' property. If it looks very grainy, just reduce the scale. For things like bricks, I use a value < 5 or else the finished texture will look very grainy in TDM. For stuff like doors, a value of about 10 looks OK.
# After adjusting the scale, click 'OK'
# Choose File -> Export as..., change the file name to 'texturename_local.tga' and click 'Export'
# On the next pop-up, untick 'RLE compression' and leave 'Origin' at 'Bottom left'. Click 'Export'. '''(ADVICE NEEDED)'''

=== Create the editor icon (JPG File) ===
# Since you've modified the image, either close and re-open the image in GIMP, or go back into your Undo History and select the original image (or cropped image if it's been cropped).
# Choose Image -> Scale Image... from the menu.
# On the dialogue, either scale it to 256x256 px (if it was a 1024x1024 image originally), or just scale it down to 25% if it was something else. Click 'Scale'. If the image looks too blurry, you can try 512 x 512.
# Choose File -> Export as..., change the file name to 'texturename_ed.jpg' and click 'Export'
# On the next pop-up, untick all the 'save data' boxes except for 'Save color profile' '''(ADVICE NEEDED)'''. Click 'Export'

=== Create TDM materials file ===
# Within your FM folder, save all your images in the appropriate TDM folder structure. Just follow the existing conventions. For example your DDS files go into 'dds/textures/darkmod/stone/brick' and your normal map and editor files go into 'textures/darkmod/stone/brick'
# Create the materials file as follows below. Give it a name like 'mybricks.mtr' and put it in the /materials folder in your FM. The material name as it appears in DarkRadiant appears at the top.

'''NOTE''': 'texturename' in this example is 'bricks_dirty'
textures/darkmod/stone/brick/bricks_dirty
{
stone
description "vine_friendly"

qer_editorimage textures/darkmod/stone/brick/bricks_dirty_ed
diffusemap textures/darkmod/stone/brick/bricks_dirty
bumpmap textures/darkmod/stone/brick/bricks_dirty_local
}

User:Frost Salamander

2025-05-17T16:53:01Z

Frost Salamander: /* Create an inventory icon for an existing model from a DR screenshot */

== TDM Files and Contents ==

{| class="wikitable"
|+ Caption text
|-
! Content !! File path !! Notes
|-
| Skins || tdm_models_decls01.pk4\skins || skin files shipped with TDM
|-
| Script Constants|| tdm_base01.pk4\script\tdm_defs.script || constant values. Useful if you need to know the literal values for use in your scripts.
|-
| Script Objects|| tdm_base01.pk4\script || various script objects for entities.
|-
| tdm_ai_humanoid_newskel.def || tdm_ai_humanoid_undead01.pk4\def\tdm_ai_humanoid_newskel.def || Base class for all TDM humanoid entities
|-
| GUI Icons || tdm_gui01.pk4\dds\guis\assets\hud\ || HUD icons. e.g. loot, potions, etc
|-
| sound shaders || tdm_sound_ambient_decls01.pk4\sound || ambient environmental sound shaders
|-
| materials definitions || tdm_textures_base01.pk4\materials || base materials files
|-
| guard model materials || tdm_ai_humanoid_guards01.pk4 || guard materials and texture files
|-
| Stim types || tdm_base01.pk4/script/tdm_stim_response.script ||
|-
| Readable textures || tdm_gui01.pk4/dds/guis/assets/readables || various parchment textures
|-
| Blueprint textures || tdm_models02.pk4 || textures/readables/blueprint01*
|-
| Light textures || tdm_textures_base01.pk4 || In both /lights and textures/lights
|}

== Creating an Image Decal with Gimp ==
# Go to somewhere like pixabay.com and search for free images. I usually filter by 'vector graphics' (e.g. PNG) because it supports alpha channel which you'll need for decals.
# Once you find an image, download it. I tend to get medium-sized versions (e.g. close to 1024 x 1024)
# Open the file in Gimp
# Scale the image to 1024x1024 pixels.
# export as TGA

== Creating a Text Decal with Gimp ==
# Open Gimp - New ->
# Set image size to 1024 x 1024 (or something more rectangular like 1024 x 512)
# Click Advanced -> Fill with: transparency
# Add text layer
# When happy with text, right-click the text layer and 'merge down' into alpha layer
# save and export as TGA.
# Create a materials file (.mtr) like so:

textures/darkmod/decals/signs/coronet
{
DECAL_MACRO
noimpact

{
blend blend
map textures/darkmod/decals/signs/coronet
}
}

== Create an inventory icon for an existing model from a DR screenshot ==
# In DarkRadiant, right-click and choose 'Create Entity...' or 'Create Model...' and choose the object you wish to use.
# in the preview window with the model showing, take a screenshot selection using something like the Windows Snipping Tool. Leave a centimeter or two of grey color around the object that we can convert to alpha transparency later.
# Save the screenshot as a JPEG somewhere on your local disk.
# Open the file with GIMP.
# From the menu, choose Layer -> Transparency -> Color to Alpha...
# A pop up will appear. Next to the Color bar there will be an eye dropper icon. This is the color picker.
# Click the color picker and then click the grey area that surrounds your image. Don't worry if it looks like it's already been converted to alpha (the grey squares). The grey squares should turn a lighter colour.
# Click OK
# TIP: If the image becomes transparent as well, this is because its color is not far off from the grey background. Reduce the 'Opacity Threshold' until the checkerboard pattern doesn't cover your image (try 0.1).
# Resize the image by clicking Image -> Scale Image... Make it 128 x 128 pixels. Click 'Scale'
# Export as DDS by clicking File -> Export As... and type a file name that ends in .dds. Choose BC3 / DXT5 compression and don't bother with mipmaps.
# Add the .dds file to your FM folder under 'dds\guis\assets\hud\inventory_icons' if you want them to be in the same folder as the stock icons.

== Creating a material using existing images (e.g. from textures.com) using GIMP ==

'''Written on May 28th, 2023 using GIMP 2.10.34'''

This will describe how to create your own texture (material) using an image found on the internet. I will use textures.com as an example.

'''Ensure that the license for whatever source you use is appropriate for TDM (e.g. allows use in video games)'''

We will end up with 3 image files and one materials file:
* diffuse map (the base image with colour details, etc)
* normal map (faked bump/dent data)
* DarkRadiant editor icon

This doesn't cover creation of a specular map. This isn't needed unless your material needs a shiny surface (e.g. metal or wet surfaces).

=== Obtain your image ===
# Log into textures.com and find an image you like under the 'Regular Photos' section ('''NOT''' 'Special Content'). Make sure it's seamless if it needs to be tiled/repeatable (e.g. for bricks or walls). If it's something like a door or window, it doesn't need to be seamless. There is normally a JPG format that that is close to or exactly 1024x1024 pixels. Download it.

=== Open your Image in GIMP ===
The first thing you may see here is a pop-up asking if you want to convert the image to 'the built-in sRGB color profile'. I'm not sure the implications of doing this but just choose 'Convert'. '''(ADVICE NEEDED)'''

=== Resize Image (if needed) ===
TDM standard resolution for textures is 1024 x 1024. However it's possible to get away with 2048 x 2048 at the cost of file size and performance.
If you can't find a 1024 x 1024 image for whatever reason (say it's 4K instead), you can scale it down:
# With the image open in GIMP, click Image -> Scale Image...
# Set the width in 'Image Size' in pixels to 1024. Make sure the width and height are 'chained' (the little link icon should be whole). The height will then scale down proportionately to match the width.

=== Crop your Image ===
This is only needed if you don't intend to use the entire image as-is (e.g. if you want to cut a door or window out of an image). Skip this section if that is not the case.
# With the image in GIMP, select the Crop Tool (Shift+C).
# Under the 'Tool Options' tab, tick the box for 'Delete cropped pixels'
# Using the crop tool select the area you want to keep on the image with your mouse, and press 'Enter' when done.

=== Create the Diffuse Map (DDS File) ===
# With the original or cropped image open in GIMP Choose File -> Export as...
# In the next popup, change the filename to 'texturename.dds' and click 'Export'.
# On the next pop-up, choose your compression format (see below) and select 'Generate mipmaps'. Under 'Mipmap Options' choose 'Filter': 'Kaiser' for best quality. Click 'Export'
- Compression:
- if your image contains an alpha channel, choose 'BC3 / DXT5'
- if your image does not contain an alpha channel, choose 'BC1 / DXT1'

=== Create the Normal Map (TGA File)===
Apart from creating the normal map, the point of the first few steps is to reduce the amount of 'noise' in the image which can lead to a grainy appearance.
# With the original or cropped image open in GIMP, select Colors -> Desaturate -> Desaturate. Click 'OK'
# Select Filters -> Blur -> Gaussian Blur. Leave the defaults and click 'OK'.
# Select Colors -> Curves and adjust the curve to 'wash out' (i.e. brighten) the image to remove any noise detail.
# Select Filters -> Generic -> Normal Map..
# The image will change to a blueish colour and you will be able to see the 'bumps'. The only thing I adjust here is the 'Scale' property. If it looks very grainy, just reduce the scale. For things like bricks, I use a value < 5 or else the finished texture will look very grainy in TDM. For stuff like doors, a value of about 10 looks OK.
# After adjusting the scale, click 'OK'
# Choose File -> Export as..., change the file name to 'texturename_local.tga' and click 'Export'
# On the next pop-up, untick 'RLE compression' and leave 'Origin' at 'Bottom left'. Click 'Export'. '''(ADVICE NEEDED)'''

=== Create the editor icon (JPG File) ===
# Since you've modified the image, either close and re-open the image in GIMP, or go back into your Undo History and select the original image (or cropped image if it's been cropped).
# Choose Image -> Scale Image... from the menu.
# On the dialogue, either scale it to 256x256 px (if it was a 1024x1024 image originally), or just scale it down to 25% if it was something else. Click 'Scale'. If the image looks too blurry, you can try 512 x 512.
# Choose File -> Export as..., change the file name to 'texturename_ed.jpg' and click 'Export'
# On the next pop-up, untick all the 'save data' boxes except for 'Save color profile' '''(ADVICE NEEDED)'''. Click 'Export'

=== Create TDM materials file ===
# Within your FM folder, save all your images in the appropriate TDM folder structure. Just follow the existing conventions. For example your DDS files go into 'dds/textures/darkmod/stone/brick' and your normal map and editor files go into 'textures/darkmod/stone/brick'
# Create the materials file as follows below. Give it a name like 'mybricks.mtr' and put it in the /materials folder in your FM. The material name as it appears in DarkRadiant appears at the top.

'''NOTE''': 'texturename' in this example is 'bricks_dirty'
textures/darkmod/stone/brick/bricks_dirty
{
stone
description "vine_friendly"

qer_editorimage textures/darkmod/stone/brick/bricks_dirty_ed
diffusemap textures/darkmod/stone/brick/bricks_dirty
bumpmap textures/darkmod/stone/brick/bricks_dirty_local
}

User:Frost Salamander

2025-05-17T16:52:45Z

Frost Salamander: /* Create an inventory icon for an existing model from a DR screenshot */

== TDM Files and Contents ==

{| class="wikitable"
|+ Caption text
|-
! Content !! File path !! Notes
|-
| Skins || tdm_models_decls01.pk4\skins || skin files shipped with TDM
|-
| Script Constants|| tdm_base01.pk4\script\tdm_defs.script || constant values. Useful if you need to know the literal values for use in your scripts.
|-
| Script Objects|| tdm_base01.pk4\script || various script objects for entities.
|-
| tdm_ai_humanoid_newskel.def || tdm_ai_humanoid_undead01.pk4\def\tdm_ai_humanoid_newskel.def || Base class for all TDM humanoid entities
|-
| GUI Icons || tdm_gui01.pk4\dds\guis\assets\hud\ || HUD icons. e.g. loot, potions, etc
|-
| sound shaders || tdm_sound_ambient_decls01.pk4\sound || ambient environmental sound shaders
|-
| materials definitions || tdm_textures_base01.pk4\materials || base materials files
|-
| guard model materials || tdm_ai_humanoid_guards01.pk4 || guard materials and texture files
|-
| Stim types || tdm_base01.pk4/script/tdm_stim_response.script ||
|-
| Readable textures || tdm_gui01.pk4/dds/guis/assets/readables || various parchment textures
|-
| Blueprint textures || tdm_models02.pk4 || textures/readables/blueprint01*
|-
| Light textures || tdm_textures_base01.pk4 || In both /lights and textures/lights
|}

== Creating an Image Decal with Gimp ==
# Go to somewhere like pixabay.com and search for free images. I usually filter by 'vector graphics' (e.g. PNG) because it supports alpha channel which you'll need for decals.
# Once you find an image, download it. I tend to get medium-sized versions (e.g. close to 1024 x 1024)
# Open the file in Gimp
# Scale the image to 1024x1024 pixels.
# export as TGA

== Creating a Text Decal with Gimp ==
# Open Gimp - New ->
# Set image size to 1024 x 1024 (or something more rectangular like 1024 x 512)
# Click Advanced -> Fill with: transparency
# Add text layer
# When happy with text, right-click the text layer and 'merge down' into alpha layer
# save and export as TGA.
# Create a materials file (.mtr) like so:

textures/darkmod/decals/signs/coronet
{
DECAL_MACRO
noimpact

{
blend blend
map textures/darkmod/decals/signs/coronet
}
}

== Create an inventory icon for an existing model from a DR screenshot ==
# In DarkRadiant, right-click and choose 'Create Entity...' or 'Create Model...' and choose the object you wish to use.
# in the preview window with the model showing, take a screenshot selection using something like the Windows Snipping Tool. Leave a centimeter or two of grey color around the object that we can convert to alpha transparency later.
# Save the screenshot as a JPEG somewhere on your local disk.
# Open the file with GIMP.
# From the menu, choose Layer -> Transparency -> Color to Alpha...
# A pop up will appear. Next to the Color bar there will be an eye dropper icon. This is the color picker.
# Click the color picker and then click the grey area that surrounds your image. Don't worry if it looks like it's already been converted to alpha (the grey squares). The grey squares should turn a lighter colour.
# Click OK
# TIP: If the image becomes transparent as well, this is because its color is not far off from the grey background. Reduce the 'Opacity Threshold' until the checkerboard pattern doesn't cover your image (try 0.1).
Resize the image by clicking Image -> Scale Image... Make it 128 x 128 pixels. Click 'Scale'
# Export as DDS by clicking File -> Export As... and type a file name that ends in .dds. Choose BC3 / DXT5 compression and don't bother with mipmaps.
# Add the .dds file to your FM folder under 'dds\guis\assets\hud\inventory_icons' if you want them to be in the same folder as the stock icons.

== Creating a material using existing images (e.g. from textures.com) using GIMP ==

'''Written on May 28th, 2023 using GIMP 2.10.34'''

This will describe how to create your own texture (material) using an image found on the internet. I will use textures.com as an example.

'''Ensure that the license for whatever source you use is appropriate for TDM (e.g. allows use in video games)'''

We will end up with 3 image files and one materials file:
* diffuse map (the base image with colour details, etc)
* normal map (faked bump/dent data)
* DarkRadiant editor icon

This doesn't cover creation of a specular map. This isn't needed unless your material needs a shiny surface (e.g. metal or wet surfaces).

=== Obtain your image ===
# Log into textures.com and find an image you like under the 'Regular Photos' section ('''NOT''' 'Special Content'). Make sure it's seamless if it needs to be tiled/repeatable (e.g. for bricks or walls). If it's something like a door or window, it doesn't need to be seamless. There is normally a JPG format that that is close to or exactly 1024x1024 pixels. Download it.

=== Open your Image in GIMP ===
The first thing you may see here is a pop-up asking if you want to convert the image to 'the built-in sRGB color profile'. I'm not sure the implications of doing this but just choose 'Convert'. '''(ADVICE NEEDED)'''

=== Resize Image (if needed) ===
TDM standard resolution for textures is 1024 x 1024. However it's possible to get away with 2048 x 2048 at the cost of file size and performance.
If you can't find a 1024 x 1024 image for whatever reason (say it's 4K instead), you can scale it down:
# With the image open in GIMP, click Image -> Scale Image...
# Set the width in 'Image Size' in pixels to 1024. Make sure the width and height are 'chained' (the little link icon should be whole). The height will then scale down proportionately to match the width.

=== Crop your Image ===
This is only needed if you don't intend to use the entire image as-is (e.g. if you want to cut a door or window out of an image). Skip this section if that is not the case.
# With the image in GIMP, select the Crop Tool (Shift+C).
# Under the 'Tool Options' tab, tick the box for 'Delete cropped pixels'
# Using the crop tool select the area you want to keep on the image with your mouse, and press 'Enter' when done.

=== Create the Diffuse Map (DDS File) ===
# With the original or cropped image open in GIMP Choose File -> Export as...
# In the next popup, change the filename to 'texturename.dds' and click 'Export'.
# On the next pop-up, choose your compression format (see below) and select 'Generate mipmaps'. Under 'Mipmap Options' choose 'Filter': 'Kaiser' for best quality. Click 'Export'
- Compression:
- if your image contains an alpha channel, choose 'BC3 / DXT5'
- if your image does not contain an alpha channel, choose 'BC1 / DXT1'

=== Create the Normal Map (TGA File)===
Apart from creating the normal map, the point of the first few steps is to reduce the amount of 'noise' in the image which can lead to a grainy appearance.
# With the original or cropped image open in GIMP, select Colors -> Desaturate -> Desaturate. Click 'OK'
# Select Filters -> Blur -> Gaussian Blur. Leave the defaults and click 'OK'.
# Select Colors -> Curves and adjust the curve to 'wash out' (i.e. brighten) the image to remove any noise detail.
# Select Filters -> Generic -> Normal Map..
# The image will change to a blueish colour and you will be able to see the 'bumps'. The only thing I adjust here is the 'Scale' property. If it looks very grainy, just reduce the scale. For things like bricks, I use a value < 5 or else the finished texture will look very grainy in TDM. For stuff like doors, a value of about 10 looks OK.
# After adjusting the scale, click 'OK'
# Choose File -> Export as..., change the file name to 'texturename_local.tga' and click 'Export'
# On the next pop-up, untick 'RLE compression' and leave 'Origin' at 'Bottom left'. Click 'Export'. '''(ADVICE NEEDED)'''

=== Create the editor icon (JPG File) ===
# Since you've modified the image, either close and re-open the image in GIMP, or go back into your Undo History and select the original image (or cropped image if it's been cropped).
# Choose Image -> Scale Image... from the menu.
# On the dialogue, either scale it to 256x256 px (if it was a 1024x1024 image originally), or just scale it down to 25% if it was something else. Click 'Scale'. If the image looks too blurry, you can try 512 x 512.
# Choose File -> Export as..., change the file name to 'texturename_ed.jpg' and click 'Export'
# On the next pop-up, untick all the 'save data' boxes except for 'Save color profile' '''(ADVICE NEEDED)'''. Click 'Export'

=== Create TDM materials file ===
# Within your FM folder, save all your images in the appropriate TDM folder structure. Just follow the existing conventions. For example your DDS files go into 'dds/textures/darkmod/stone/brick' and your normal map and editor files go into 'textures/darkmod/stone/brick'
# Create the materials file as follows below. Give it a name like 'mybricks.mtr' and put it in the /materials folder in your FM. The material name as it appears in DarkRadiant appears at the top.

'''NOTE''': 'texturename' in this example is 'bricks_dirty'
textures/darkmod/stone/brick/bricks_dirty
{
stone
description "vine_friendly"

qer_editorimage textures/darkmod/stone/brick/bricks_dirty_ed
diffusemap textures/darkmod/stone/brick/bricks_dirty
bumpmap textures/darkmod/stone/brick/bricks_dirty_local
}

User:Frost Salamander

2025-05-17T16:34:15Z

Frost Salamander: /* Create an inventory icon for an existing model from a DR screenshot */

== TDM Files and Contents ==

{| class="wikitable"
|+ Caption text
|-
! Content !! File path !! Notes
|-
| Skins || tdm_models_decls01.pk4\skins || skin files shipped with TDM
|-
| Script Constants|| tdm_base01.pk4\script\tdm_defs.script || constant values. Useful if you need to know the literal values for use in your scripts.
|-
| Script Objects|| tdm_base01.pk4\script || various script objects for entities.
|-
| tdm_ai_humanoid_newskel.def || tdm_ai_humanoid_undead01.pk4\def\tdm_ai_humanoid_newskel.def || Base class for all TDM humanoid entities
|-
| GUI Icons || tdm_gui01.pk4\dds\guis\assets\hud\ || HUD icons. e.g. loot, potions, etc
|-
| sound shaders || tdm_sound_ambient_decls01.pk4\sound || ambient environmental sound shaders
|-
| materials definitions || tdm_textures_base01.pk4\materials || base materials files
|-
| guard model materials || tdm_ai_humanoid_guards01.pk4 || guard materials and texture files
|-
| Stim types || tdm_base01.pk4/script/tdm_stim_response.script ||
|-
| Readable textures || tdm_gui01.pk4/dds/guis/assets/readables || various parchment textures
|-
| Blueprint textures || tdm_models02.pk4 || textures/readables/blueprint01*
|-
| Light textures || tdm_textures_base01.pk4 || In both /lights and textures/lights
|}

== Creating an Image Decal with Gimp ==
# Go to somewhere like pixabay.com and search for free images. I usually filter by 'vector graphics' (e.g. PNG) because it supports alpha channel which you'll need for decals.
# Once you find an image, download it. I tend to get medium-sized versions (e.g. close to 1024 x 1024)
# Open the file in Gimp
# Scale the image to 1024x1024 pixels.
# export as TGA

== Creating a Text Decal with Gimp ==
# Open Gimp - New ->
# Set image size to 1024 x 1024 (or something more rectangular like 1024 x 512)
# Click Advanced -> Fill with: transparency
# Add text layer
# When happy with text, right-click the text layer and 'merge down' into alpha layer
# save and export as TGA.
# Create a materials file (.mtr) like so:

textures/darkmod/decals/signs/coronet
{
DECAL_MACRO
noimpact

{
blend blend
map textures/darkmod/decals/signs/coronet
}
}

== Create an inventory icon for an existing model from a DR screenshot ==
# In DarkRadiant, right-click and choose 'Create Entity...' or 'Create Model...' and choose the object you wish to use.
# in the preview window with the model showing, take a screenshot selection using something like the Windows Snipping Tool. Leave a centimeter or two of grey color around the object that we can convert to alpha transparency later.
# Save the screenshot as a JPEG somewhere on your local disk.
# Open the file with GIMP.
# From the menu, choose Layer -> Transparency -> Color to Alpha...
# A pop up will appear. Next to the Color bar there will be an eye dropper icon. This is the color picker.
# Click the color picker and then click the grey area that surrounds your image. Don't worry if it looks like it's already been converted to alpha (the grey squares). The grey squares should turn a lighter colour.
# Click OK
# Resize the image by clicking Image -> Scale Image... Make it 128 x 128 pixels. Click 'Scale'
# Export as DDS by clicking File -> Export As... and type a file name that ends in .dds. Choose BC3 / DXT5 compression and don't bother with mipmaps.
# Add the .dds file to your FM folder under 'dds\guis\assets\hud\inventory_icons' if you want them to be in the same folder as the stock icons.

== Creating a material using existing images (e.g. from textures.com) using GIMP ==

'''Written on May 28th, 2023 using GIMP 2.10.34'''

This will describe how to create your own texture (material) using an image found on the internet. I will use textures.com as an example.

'''Ensure that the license for whatever source you use is appropriate for TDM (e.g. allows use in video games)'''

We will end up with 3 image files and one materials file:
* diffuse map (the base image with colour details, etc)
* normal map (faked bump/dent data)
* DarkRadiant editor icon

This doesn't cover creation of a specular map. This isn't needed unless your material needs a shiny surface (e.g. metal or wet surfaces).

=== Obtain your image ===
# Log into textures.com and find an image you like under the 'Regular Photos' section ('''NOT''' 'Special Content'). Make sure it's seamless if it needs to be tiled/repeatable (e.g. for bricks or walls). If it's something like a door or window, it doesn't need to be seamless. There is normally a JPG format that that is close to or exactly 1024x1024 pixels. Download it.

=== Open your Image in GIMP ===
The first thing you may see here is a pop-up asking if you want to convert the image to 'the built-in sRGB color profile'. I'm not sure the implications of doing this but just choose 'Convert'. '''(ADVICE NEEDED)'''

=== Resize Image (if needed) ===
TDM standard resolution for textures is 1024 x 1024. However it's possible to get away with 2048 x 2048 at the cost of file size and performance.
If you can't find a 1024 x 1024 image for whatever reason (say it's 4K instead), you can scale it down:
# With the image open in GIMP, click Image -> Scale Image...
# Set the width in 'Image Size' in pixels to 1024. Make sure the width and height are 'chained' (the little link icon should be whole). The height will then scale down proportionately to match the width.

=== Crop your Image ===
This is only needed if you don't intend to use the entire image as-is (e.g. if you want to cut a door or window out of an image). Skip this section if that is not the case.
# With the image in GIMP, select the Crop Tool (Shift+C).
# Under the 'Tool Options' tab, tick the box for 'Delete cropped pixels'
# Using the crop tool select the area you want to keep on the image with your mouse, and press 'Enter' when done.

=== Create the Diffuse Map (DDS File) ===
# With the original or cropped image open in GIMP Choose File -> Export as...
# In the next popup, change the filename to 'texturename.dds' and click 'Export'.
# On the next pop-up, choose your compression format (see below) and select 'Generate mipmaps'. Under 'Mipmap Options' choose 'Filter': 'Kaiser' for best quality. Click 'Export'
- Compression:
- if your image contains an alpha channel, choose 'BC3 / DXT5'
- if your image does not contain an alpha channel, choose 'BC1 / DXT1'

=== Create the Normal Map (TGA File)===
Apart from creating the normal map, the point of the first few steps is to reduce the amount of 'noise' in the image which can lead to a grainy appearance.
# With the original or cropped image open in GIMP, select Colors -> Desaturate -> Desaturate. Click 'OK'
# Select Filters -> Blur -> Gaussian Blur. Leave the defaults and click 'OK'.
# Select Colors -> Curves and adjust the curve to 'wash out' (i.e. brighten) the image to remove any noise detail.
# Select Filters -> Generic -> Normal Map..
# The image will change to a blueish colour and you will be able to see the 'bumps'. The only thing I adjust here is the 'Scale' property. If it looks very grainy, just reduce the scale. For things like bricks, I use a value < 5 or else the finished texture will look very grainy in TDM. For stuff like doors, a value of about 10 looks OK.
# After adjusting the scale, click 'OK'
# Choose File -> Export as..., change the file name to 'texturename_local.tga' and click 'Export'
# On the next pop-up, untick 'RLE compression' and leave 'Origin' at 'Bottom left'. Click 'Export'. '''(ADVICE NEEDED)'''

=== Create the editor icon (JPG File) ===
# Since you've modified the image, either close and re-open the image in GIMP, or go back into your Undo History and select the original image (or cropped image if it's been cropped).
# Choose Image -> Scale Image... from the menu.
# On the dialogue, either scale it to 256x256 px (if it was a 1024x1024 image originally), or just scale it down to 25% if it was something else. Click 'Scale'. If the image looks too blurry, you can try 512 x 512.
# Choose File -> Export as..., change the file name to 'texturename_ed.jpg' and click 'Export'
# On the next pop-up, untick all the 'save data' boxes except for 'Save color profile' '''(ADVICE NEEDED)'''. Click 'Export'

=== Create TDM materials file ===
# Within your FM folder, save all your images in the appropriate TDM folder structure. Just follow the existing conventions. For example your DDS files go into 'dds/textures/darkmod/stone/brick' and your normal map and editor files go into 'textures/darkmod/stone/brick'
# Create the materials file as follows below. Give it a name like 'mybricks.mtr' and put it in the /materials folder in your FM. The material name as it appears in DarkRadiant appears at the top.

'''NOTE''': 'texturename' in this example is 'bricks_dirty'
textures/darkmod/stone/brick/bricks_dirty
{
stone
description "vine_friendly"

qer_editorimage textures/darkmod/stone/brick/bricks_dirty_ed
diffusemap textures/darkmod/stone/brick/bricks_dirty
bumpmap textures/darkmod/stone/brick/bricks_dirty_local
}

Attaching Props to AI

2025-05-13T19:42:44Z

Frost Salamander: /* Belt Objects - Keys */

Attaching things to AI is an important way to make your AI unique.

There are two ways to attach things (hereafter referred to as 'props') to AI. Each has its strengths and weaknesses.

'''''To attach working weapons and heads see [[Adding Heads and Weapons to AI]]'''''

== Using Def_Attach ==

'''Benefits:''' The mapper can easily attach pre-existing prop entities; no fiddling with positions or rotations. More importantly, def_attached entities often adjusts AI animations appropriately (eg, def_attaching a torch automatically makes the AI use the 'torch' animations).

'''Weaknesses:''' It is time-consuming to make prop entities that don't already exist. Def_attached objects will not be visible in DR.

Each AI has a set of pre-determined coordinates (attachment points). The mapper can attach things to these points by using the following spawnargs in an AI's entity window:

def_attach5 [entity name]
pos_attach5 [attachment point name]

The number is arbitrary. As long as both lines have the same number, you could use 999. Best to stay away from numbers 1-5, however, as some AI come with default props (pauldrons, weapons, etc), and you could overwrite them.

'''[entity name]''' is the entity that you want to attach, like "atdm:prop_torch_gothic_on". You can find a list of preset attachable objects in prop_items.def and prop_wearable_items.def. Or see the quick list below.

'''[attachment point name]''' is the name of the predefined point you want to attach the object to, like "hand_l". See the list of preset attachment points below.

This image indicates some common attachment points. You can cut and paste the names below:

http://www.mindplaces.com/save/attachment_points.jpg

1. '''"hip_sheath_l"'''

This is designed for sheathed weapons on the hip.

2. '''"hand_l"'''

The left hand, used for torches, bottles, etc. You can attach a weapon to this hand but AI will not attack with it.

3. '''"belt_back_right"'''

This is on the back of the belt on the right hand side, designed for purses, keys, or other things players may want to pickpocket.

4. '''"hand_r"'''

The right hand. Generally reserved for weapon use.

5. '''"slung_across_back_rl"'''

This is primarily used for weapons worn on the back, like hammers or bows.

=== List of Attachable Objects ===
The following are prop entities already created for def_attaching. After you select one and copy its spawnargs into the AI's entity window in DR, you may need to change the ''attach'' number to something unique.

For information on making new attachment points, or positioning new entities, see [[Attachment Positions]].

==== Hand Objects - Lights ====

def_attach5 atdm:prop_torch_on ''// a regular, lit torch''
pos_attach5 hand_l

def_attach5 atdm:prop_torch_gothic_on ''// a lit torch with a cage''
pos_attach5 hand_l

def_attach5 atdm:prop_lantern_on ''// a brass oil lantern''
pos_attach5 hand_l

def_attach5 atdm:prop_lantern02_on ''// an alternate metal oil lantern''
pos_attach5 hand_l

==== Hand Objects - Other Than Lights ====

def_attach5 atdm:prop_halberd ''// a long halberd; decorative only--dropped when AI alerted''
pos_attach5 hand_l

def_attach5 atdm:prop_winebottle ''// AI holds bottle and occasionally drinks from it''
pos_attach5 hand_l

def_attach5 atdm:prop_cards ''// AI holds hand of cards and occasionally draws another one. For use when sitting.''
pos_attach5 hand_l

==== Belt Objects ====

def_attach6 atdm:prop_lootbag ''// used for loot''
pos_attach6 belt_back_right

def_attach6 atdm:prop_belt_pouch ''// used for decoration''
pos_attach6 belt_back_right

def_attach6 atdm:prop_potion_healing ''// for pick-pocketing; AI will not use it.''
pos_attach6 belt_back_right

def_attach6 atdm:prop_smithyhammer ''// a simple work hammer, decorative only at the moment''
pos_attach6 hip_sheath_l

==== Belt Objects - Keys ====
''Example of key attachment by bikerdude''

def_attach6 atdm:prop_key_simple
pos_attach6 belt_back_right
name_attach6 gate_key
set inv_name on gate_key gate key ''// name shown in inventory''
set name on gate_key gate_key

More info can be found on the following thread - http://forums.thedarkmod.com/topic/13084-ai-attach-keys/

Other attachable key styles include:
atdm:prop_key_gold
atdm:prop_silverkey
atdm:prop_key_fancy01
atdm:prop_key_padlock

=== Changing the Behavior of Def-Attached Props ===
''by Geep''

As with the Keys example above, you have to name the prop:
name_attach[number] [my_prop_name] ''where [number] is the def_attach number and my_prop_name contains no spaces''

Then reference that name:
set [spawnarg] on [my_prop_name] [value]

For instance:
set frob_distance on gate_key 100

This can be done not just for props you attach, but for those pre-provisioned with an AI. For example, consider an archer whose quiver comes with 1 frobable arrow. Suppose you wish to override the default frob behavior. If you examine the archer with the Entity Inspector (including inherited items), you will find that there's an arrow on def_attach3, but it is unnamed. Fix that:
name_attach3 quiver_arrow
Then, to replace the default frob action with a function FrobbedQuiverArrow you defined in <fm>.script:
set frob_action_script on quiver_arrow FrobbedQuiverArrow

''Suggested by Destined''

If you want to instead use Stimulus/Response to affect behavior, note that props that are def_attached are not visible as selectable objects in DR. So the usual direct method of using the S/R Editor is not possible.

Instead, create all the S/R spawnargs manually. The easiest way to do that is create a dummy entity and, with it selected, set up the response effects you want with the S/R Editor. Once you have generated all the spawnargs you need, apply each to your AI as:
set [S/R spawnarg] on [my_prop_name] [S/R value] ''where [my_prop_name] might be "quiver_arrow" from above''

If there is any problem when overriding a behavior for an existing prop, a safe bet is to write a new definition. Thus, in our arrow example, copy the definition of atdm:prop_quiver_arrow to a new definition file, rename the definition to a unique name (e.g. "atdm:prop_quiver_arrow_special"). Again, use a dummy entity to create the S/R spawnargs. Then add those spawnargs to the definition, and change the spawnarg def_attach_3 on the AI to the new name.

This latter alternative is especially useful if you want this response on multiple AI: just set up the S/R spawnargs once, then easily give the special arrow to various AI by changing the def_attach_3 spawnarg.

=== Difficulty Levels ===
''by Spooks, [https://forums.thedarkmod.com/index.php?/topic/9082-newbie-darkradiant-questions/&do=findComment&comment=471432 2022 forum post]''

[https://forums.thedarkmod.com/index.php?/topic/9082-newbie-darkradiant-questions/page/264/&tab=comments#comment-387803 Traditionally], it was thought you cannot directly vary the presence of a def_attached item, like a key, by Difficulty Level. Specifically, using diff_x_nospawn doesn't work, because the def_attached item is automatically spawned when the AI is spawned, and then it is too late for spawn prevention with diff_x_nospawn. (The recommended work-around was to clone your AI, then make them differ in their diff_n_nospawn spawnargs and their attached items.)

However, it turns out there is a way to conditionally-spawn the def_attached item ''after'' the AI is spawned: use diff_x_change_n and diff_x_arg_n. As an example, consider an AI carrying a grey steel key on its belt. The AI would typically have spawnargs like:

def_attach6 atdm:prop_key_simple_steel
name_attach6 test_key
pos_attach6 belt_back_right
set inv_name on test_key A Key For Testing
set name on test_key test_key

Now, let's redo it, so the key is only present on the easiest difficulty (diff_0). First, and required to make this work, '''DON'T''' have present (even blank or defaulted) any unconditional spawnargs related to the item we want conditional, e.g, all of those spawnargs in our example above. Instead, each line above becomes a pair of spawnargs, of form diff_0_change_n and diff_0_arg_n:

diff_0_change_0 def_attach6
diff_0_arg_0 atdm:prop_key_simple_steel

diff_0_change_1 name_attach6
diff_0_arg_1 test_key

diff_0_change_2 pos_attach6
diff_0_arg_2 belt_back_right

diff_0_change_3 set inv_name on test_key
diff_0_arg_3 A Key For Testing

diff_0_change_4 set name on test_key
diff_0_arg_4 test_key

== Binding ==

'''Benefits:''' You can bind any object to an AI, so it is a great deal more flexible. You can also see and position the object in DR.

'''Weaknesses:''' Bound objects cannot affect AI animations. You must adjust each object individually. An AI can't use a bound key to open locked doors (but see [[Doors]] for a workaround).

See [[BindToJoint]] and [[Attaching Items]] for more info on using bind.

== See Also ==
[[Def attach]] applied to non-AI entities, such as combined light sources.
{{tutorial-ai}}

Setting Reverb Data of Rooms (EAX)

2025-05-10T14:50:28Z

Frost Salamander: /* Preset Values */

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 [https://github.com/kcat/openal-soft openal-soft]) without any requirements on sound card.

= General =

== Setup ==

EFX for a fan mission can be configured with or without a configuration file. However, fileless configuration is only supported for [[Setting_Reverb_Data_of_Rooms_(EAX)#Presets_(Version_2)|EFX presets]].

== EFX file ==
The EFX info for a map should be stored in the file "<tt>efxs/<mapname>.efx</tt>", 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 "<tt>OpenAL EFX</tt>" in sound settings in the main menu, otherwise TDM won't even try to load the 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:
* <tt>Version 1</tt> was supported by TDM from the very beginning. It uses some non-standard terms and quantities, which makes it hard to work with.
* <tt>Version 2</tt> 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 <tt>reverb</tt> keyword for Version 1 definitions, and <tt>eaxreverb</tt> 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 "<tt>name</tt>" 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 <tt>_area<num></tt> (where <num> is the portal area number), e.g. <tt>_area15</tt>.
'''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 "<tt>reloadSounds</tt>" 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 "<tt>no_efx</tt>" 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 "<tt>reloadDecls</tt>" 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 "<tt>no_efx</tt>" keyword (see issue [http://bugs.thedarkmod.com/view.php?id=4688 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 [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#95 OpenAL Effects Extension Guide](pages 95-101).
The short list is also available in a table on [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#66 page 66 of the guide]:

[[File:Eaxreverb_properties_screenshot.png|500px]]

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

== Presets (Version 2) ==
Presets can be set in 2 ways:
* in the .efx file
* As of TDM 2.13, the '''efx_preset''' spawnarg on the location entity for the location where you want to use the effect.

=== File Method ===

There is one special property <tt>PRESET</tt>, 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.

=== Location Entity Method ===
On the location entity where you want to use the preset, set the spawnarg '''efx_preset''' to the value of the preset. For example:

<pre>
efx_preset CITY_SUBWAY
</pre>

If using this method no .efx file is required at all, but using both methods simultaneously is supported. In the case that both are used to set the preset value for a single location, the spawnarg value will take precedence.

=== Preset Values ===
The presets were taken from OpenAL-Soft implementation which TDM uses.
Here is the full list of preset names:

<pre style="height:350px; overflow:scroll;">
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
</pre>

Their definitions can be seen in [https://github.com/kcat/openal-soft/blob/master/include/AL/efx-presets.h efx-presets.h] from OpenAL-Soft source code.

<div class="mw-collapsible mw-collapsed" data-expandtext="Show" data-collapsetext="Hide">

== 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.

<div class="mw-collapsible-content">

* '''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:

{| style="margin: 0.5em; margin-left: 2em; border: 1px solid #a0a0a0; text-align: right; border-collapse: collapse;" cellpadding="2" border="1"

|-
!bgcolor="#ffdead"|Flag decimal
!bgcolor="#ffdead"|Flag binary
!bgcolor="#ffdead"|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.
</div>
</div>

=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=

See the "EFX Reverb" column of '''[[Fan_Missions_for_The_Dark_Mod|Fan Missions page]]'''. Missions with "Yes" have EFX Reverb.
<br>Most missions use v2.0 presets but a few missions such as "Volta and the Stone" and Behind Closed Doors use v1.0 settings.

=See Also=

The Version 2 definitions were implemented due to [http://bugs.thedarkmod.com/view.php?id=4815 issue 4815], it has some brief explanation.

A tutorial based around EFX can be found [http://forums.thedarkmod.com/topic/19205-getting-started-with-the-efx-room-reverb-system-wip/ here]

An old demonstration map of EAX in TDM is included [http://forums.thedarkmod.com/topic/11045-environmental-audio-extensions-eax-in-tdm/ here]

A discussion about no_efx is [http://forums.thedarkmod.com/topic/19213-efx-discussion here]

The first version of this article was written by Ishtvan [https://forums.thedarkmod.com/index.php?/topic/2071-setting-reverb-data-in-new-soundengine-wiki/ here]

[[Category:Sound]]
[[Category:Tutorial]]

User:Frost Salamander

2025-05-05T14:16:14Z

Frost Salamander:

== TDM Files and Contents ==

{| class="wikitable"
|+ Caption text
|-
! Content !! File path !! Notes
|-
| Skins || tdm_models_decls01.pk4\skins || skin files shipped with TDM
|-
| Script Constants|| tdm_base01.pk4\script\tdm_defs.script || constant values. Useful if you need to know the literal values for use in your scripts.
|-
| Script Objects|| tdm_base01.pk4\script || various script objects for entities.
|-
| tdm_ai_humanoid_newskel.def || tdm_ai_humanoid_undead01.pk4\def\tdm_ai_humanoid_newskel.def || Base class for all TDM humanoid entities
|-
| GUI Icons || tdm_gui01.pk4\dds\guis\assets\hud\ || HUD icons. e.g. loot, potions, etc
|-
| sound shaders || tdm_sound_ambient_decls01.pk4\sound || ambient environmental sound shaders
|-
| materials definitions || tdm_textures_base01.pk4\materials || base materials files
|-
| guard model materials || tdm_ai_humanoid_guards01.pk4 || guard materials and texture files
|-
| Stim types || tdm_base01.pk4/script/tdm_stim_response.script ||
|-
| Readable textures || tdm_gui01.pk4/dds/guis/assets/readables || various parchment textures
|-
| Blueprint textures || tdm_models02.pk4 || textures/readables/blueprint01*
|-
| Light textures || tdm_textures_base01.pk4 || In both /lights and textures/lights
|}

== Creating an Image Decal with Gimp ==
# Go to somewhere like pixabay.com and search for free images. I usually filter by 'vector graphics' (e.g. PNG) because it supports alpha channel which you'll need for decals.
# Once you find an image, download it. I tend to get medium-sized versions (e.g. close to 1024 x 1024)
# Open the file in Gimp
# Scale the image to 1024x1024 pixels.
# export as TGA

== Creating a Text Decal with Gimp ==
# Open Gimp - New ->
# Set image size to 1024 x 1024 (or something more rectangular like 1024 x 512)
# Click Advanced -> Fill with: transparency
# Add text layer
# When happy with text, right-click the text layer and 'merge down' into alpha layer
# save and export as TGA.
# Create a materials file (.mtr) like so:

textures/darkmod/decals/signs/coronet
{
DECAL_MACRO
noimpact

{
blend blend
map textures/darkmod/decals/signs/coronet
}
}

== Create an inventory icon for an existing model from a DR screenshot ==
# In DarkRadiant, right-click and choose 'Create Entity...' or 'Create Model...' and choose the object you wish to use.
# in the preview window with the model showing, take a screenshot selection using something like the Windows Snipping Tool. Leave a centimeter or two of grey color around the object that we can convert to alpha transparency later.
# Save the screenshot as a JPEG somewhere on your local disk.
# Open the file with GIMP.
# From the menu, choose Layer -> Transparency -> Color to Alpha...
# A pop up will appear. Next to the Color bar there will be an eye dropper icon. This is the color picker.
# Click the color picker and then click the grey area that surrounds your image. Don't worry if it looks like it's already been converted to alpha (the grey squares). The grey squares should turn a lighter colour.
# Click OK
# Resize the image by clicking Image -> Scale Image... Make it 128 x 128 pixels. Click 'Scale'
# Export as DDS by clicking File -> Export As... and type a file name that ends in .dds. Choose BC£ / DXT5 compression and don't bother with mipmaps.
# Add the .dds file to your FM folder under 'dds\guis\assets\hud\inventory_icons' if you want them to be in the same folder as the stock icons.

== Creating a material using existing images (e.g. from textures.com) using GIMP ==

'''Written on May 28th, 2023 using GIMP 2.10.34'''

This will describe how to create your own texture (material) using an image found on the internet. I will use textures.com as an example.

'''Ensure that the license for whatever source you use is appropriate for TDM (e.g. allows use in video games)'''

We will end up with 3 image files and one materials file:
* diffuse map (the base image with colour details, etc)
* normal map (faked bump/dent data)
* DarkRadiant editor icon

This doesn't cover creation of a specular map. This isn't needed unless your material needs a shiny surface (e.g. metal or wet surfaces).

=== Obtain your image ===
# Log into textures.com and find an image you like under the 'Regular Photos' section ('''NOT''' 'Special Content'). Make sure it's seamless if it needs to be tiled/repeatable (e.g. for bricks or walls). If it's something like a door or window, it doesn't need to be seamless. There is normally a JPG format that that is close to or exactly 1024x1024 pixels. Download it.

=== Open your Image in GIMP ===
The first thing you may see here is a pop-up asking if you want to convert the image to 'the built-in sRGB color profile'. I'm not sure the implications of doing this but just choose 'Convert'. '''(ADVICE NEEDED)'''

=== Resize Image (if needed) ===
TDM standard resolution for textures is 1024 x 1024. However it's possible to get away with 2048 x 2048 at the cost of file size and performance.
If you can't find a 1024 x 1024 image for whatever reason (say it's 4K instead), you can scale it down:
# With the image open in GIMP, click Image -> Scale Image...
# Set the width in 'Image Size' in pixels to 1024. Make sure the width and height are 'chained' (the little link icon should be whole). The height will then scale down proportionately to match the width.

=== Crop your Image ===
This is only needed if you don't intend to use the entire image as-is (e.g. if you want to cut a door or window out of an image). Skip this section if that is not the case.
# With the image in GIMP, select the Crop Tool (Shift+C).
# Under the 'Tool Options' tab, tick the box for 'Delete cropped pixels'
# Using the crop tool select the area you want to keep on the image with your mouse, and press 'Enter' when done.

=== Create the Diffuse Map (DDS File) ===
# With the original or cropped image open in GIMP Choose File -> Export as...
# In the next popup, change the filename to 'texturename.dds' and click 'Export'.
# On the next pop-up, choose your compression format (see below) and select 'Generate mipmaps'. Under 'Mipmap Options' choose 'Filter': 'Kaiser' for best quality. Click 'Export'
- Compression:
- if your image contains an alpha channel, choose 'BC3 / DXT5'
- if your image does not contain an alpha channel, choose 'BC1 / DXT1'

=== Create the Normal Map (TGA File)===
Apart from creating the normal map, the point of the first few steps is to reduce the amount of 'noise' in the image which can lead to a grainy appearance.
# With the original or cropped image open in GIMP, select Colors -> Desaturate -> Desaturate. Click 'OK'
# Select Filters -> Blur -> Gaussian Blur. Leave the defaults and click 'OK'.
# Select Colors -> Curves and adjust the curve to 'wash out' (i.e. brighten) the image to remove any noise detail.
# Select Filters -> Generic -> Normal Map..
# The image will change to a blueish colour and you will be able to see the 'bumps'. The only thing I adjust here is the 'Scale' property. If it looks very grainy, just reduce the scale. For things like bricks, I use a value < 5 or else the finished texture will look very grainy in TDM. For stuff like doors, a value of about 10 looks OK.
# After adjusting the scale, click 'OK'
# Choose File -> Export as..., change the file name to 'texturename_local.tga' and click 'Export'
# On the next pop-up, untick 'RLE compression' and leave 'Origin' at 'Bottom left'. Click 'Export'. '''(ADVICE NEEDED)'''

=== Create the editor icon (JPG File) ===
# Since you've modified the image, either close and re-open the image in GIMP, or go back into your Undo History and select the original image (or cropped image if it's been cropped).
# Choose Image -> Scale Image... from the menu.
# On the dialogue, either scale it to 256x256 px (if it was a 1024x1024 image originally), or just scale it down to 25% if it was something else. Click 'Scale'. If the image looks too blurry, you can try 512 x 512.
# Choose File -> Export as..., change the file name to 'texturename_ed.jpg' and click 'Export'
# On the next pop-up, untick all the 'save data' boxes except for 'Save color profile' '''(ADVICE NEEDED)'''. Click 'Export'

=== Create TDM materials file ===
# Within your FM folder, save all your images in the appropriate TDM folder structure. Just follow the existing conventions. For example your DDS files go into 'dds/textures/darkmod/stone/brick' and your normal map and editor files go into 'textures/darkmod/stone/brick'
# Create the materials file as follows below. Give it a name like 'mybricks.mtr' and put it in the /materials folder in your FM. The material name as it appears in DarkRadiant appears at the top.

'''NOTE''': 'texturename' in this example is 'bricks_dirty'
textures/darkmod/stone/brick/bricks_dirty
{
stone
description "vine_friendly"

qer_editorimage textures/darkmod/stone/brick/bricks_dirty_ed
diffusemap textures/darkmod/stone/brick/bricks_dirty
bumpmap textures/darkmod/stone/brick/bricks_dirty_local
}

Setting Reverb Data of Rooms (EAX)

2025-01-12T12:34:53Z

Frost Salamander: /* Location Entity Method */

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 [https://github.com/kcat/openal-soft openal-soft]) without any requirements on sound card.

= General =

== Setup ==

EFX for a fan mission can be configured with or without a configuration file. However, fileless configuration is only supported for [[Setting_Reverb_Data_of_Rooms_(EAX)#Presets_(Version_2)|EFX presets]].

== EFX file ==
The EFX info for a map should be stored in the file "<tt>efxs/<mapname>.efx</tt>", 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 "<tt>OpenAL EFX</tt>" in sound settings in the main menu, otherwise TDM won't even try to load the 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:
* <tt>Version 1</tt> was supported by TDM from the very beginning. It uses some non-standard terms and quantities, which makes it hard to work with.
* <tt>Version 2</tt> 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 <tt>reverb</tt> keyword for Version 1 definitions, and <tt>eaxreverb</tt> 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 "<tt>name</tt>" 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 <tt>_area<num></tt> (where <num> is the portal area number), e.g. <tt>_area15</tt>.
'''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 "<tt>reloadSounds</tt>" 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 "<tt>no_efx</tt>" 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 "<tt>reloadDecls</tt>" 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 "<tt>no_efx</tt>" keyword (see issue [http://bugs.thedarkmod.com/view.php?id=4688 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 [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#95 OpenAL Effects Extension Guide](pages 95-101).
The short list is also available in a table on [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#66 page 66 of the guide]:

[[File:Eaxreverb_properties_screenshot.png|500px]]

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

== Presets (Version 2) ==
Presets can be set in 2 ways:
* in the .efx file
* As of TDM 2.13, the '''efx_preset''' spawnarg on the location entity for the location where you want to use the effect.

=== File Method ===

There is one special property <tt>PRESET</tt>, 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.

=== Location Entity Method ===
On the location entity where you want to use the preset, set the spawnarg '''efx_preset''' to the value of the preset. For example:

<pre>
efx_preset CITY_SUBWAY
</pre>

If using this method no .efx file is required at all, but using both methods simultaneously is supported. In the case that both are used to set the preset value for a single location, the spawnarg value will take precedence.

=== Preset Values ===
The presets were taken from OpenAL-Soft implementation which TDM uses.
Here is the full list of preset names:

<pre style="height:350px; overflow:scroll;">
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
</pre>

Their definitions can be seen in [https://github.com/kcat/openal-soft/blob/master/include/AL/efx-presets.h efx-presets.h] from OpenAL-Soft source code.

<div class="mw-collapsible mw-collapsed" data-expandtext="Show" data-collapsetext="Hide">

== 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.

<div class="mw-collapsible-content">

* '''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:

{| style="margin: 0.5em; margin-left: 2em; border: 1px solid #a0a0a0; text-align: right; border-collapse: collapse;" cellpadding="2" border="1"

|-
!bgcolor="#ffdead"|Flag decimal
!bgcolor="#ffdead"|Flag binary
!bgcolor="#ffdead"|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.
</div>
</div>

=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=

See the "EFX Reverb" column of '''[[Fan_Missions_for_The_Dark_Mod|Fan Missions page]]'''. Missions with "Yes" have EFX Reverb.
<br>Most missions use v2.0 presets but a few missions such as "Volta and the Stone" and Behind Closed Doors use v1.0 settings.

=See Also=

The Version 2 definitions were implemented due to [http://bugs.thedarkmod.com/view.php?id=4815 issue 4815], it has some brief explanation.

A tutorial based around EFX can be found [http://forums.thedarkmod.com/topic/19205-getting-started-with-the-efx-room-reverb-system-wip/ here]

An old demonstration map of EAX in TDM is included [http://forums.thedarkmod.com/topic/11045-environmental-audio-extensions-eax-in-tdm/ here]

A discussion about no_efx is [http://forums.thedarkmod.com/topic/19213-efx-discussion here]

The first version of this article was written by Ishtvan [https://forums.thedarkmod.com/index.php?/topic/2071-setting-reverb-data-in-new-soundengine-wiki/ here]

[[Category:Sound]]
[[Category:Tutorial]]

Setting Reverb Data of Rooms (EAX)

2025-01-11T22:03:05Z

Frost Salamander: /* Location Entity Method */

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 [https://github.com/kcat/openal-soft openal-soft]) without any requirements on sound card.

= General =

== Setup ==

EFX for a fan mission can be configured with or without a configuration file. However, fileless configuration is only supported for [[Setting_Reverb_Data_of_Rooms_(EAX)#Presets_(Version_2)|EFX presets]].

== EFX file ==
The EFX info for a map should be stored in the file "<tt>efxs/<mapname>.efx</tt>", 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 "<tt>OpenAL EFX</tt>" in sound settings in the main menu, otherwise TDM won't even try to load the 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:
* <tt>Version 1</tt> was supported by TDM from the very beginning. It uses some non-standard terms and quantities, which makes it hard to work with.
* <tt>Version 2</tt> 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 <tt>reverb</tt> keyword for Version 1 definitions, and <tt>eaxreverb</tt> 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 "<tt>name</tt>" 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 <tt>_area<num></tt> (where <num> is the portal area number), e.g. <tt>_area15</tt>.
'''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 "<tt>reloadSounds</tt>" 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 "<tt>no_efx</tt>" 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 "<tt>reloadDecls</tt>" 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 "<tt>no_efx</tt>" keyword (see issue [http://bugs.thedarkmod.com/view.php?id=4688 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 [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#95 OpenAL Effects Extension Guide](pages 95-101).
The short list is also available in a table on [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#66 page 66 of the guide]:

[[File:Eaxreverb_properties_screenshot.png|500px]]

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

== Presets (Version 2) ==
Presets can be set in 2 ways:
* in the .efx file
* As of TDM 2.13, the '''efx_preset''' spawnarg on the location entity for the location where you want to use the effect.

=== File Method ===

There is one special property <tt>PRESET</tt>, 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.

=== Location Entity Method ===
On the location entity where you want to use the preset, set the spawnarg '''efx_preset''' to the value of the preset. For example:

<pre>
efx_preset CITY_SUBWAY
</pre>

If using this method the .efx file is required at all, but using both methods simultaneously is supported. In the case that both are used to set the preset value for a single location, the spawnarg value will take precedence.

=== Preset Values ===
The presets were taken from OpenAL-Soft implementation which TDM uses.
Here is the full list of preset names:

<pre style="height:350px; overflow:scroll;">
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
</pre>

Their definitions can be seen in [https://github.com/kcat/openal-soft/blob/master/include/AL/efx-presets.h efx-presets.h] from OpenAL-Soft source code.

<div class="mw-collapsible mw-collapsed" data-expandtext="Show" data-collapsetext="Hide">

== 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.

<div class="mw-collapsible-content">

* '''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:

{| style="margin: 0.5em; margin-left: 2em; border: 1px solid #a0a0a0; text-align: right; border-collapse: collapse;" cellpadding="2" border="1"

|-
!bgcolor="#ffdead"|Flag decimal
!bgcolor="#ffdead"|Flag binary
!bgcolor="#ffdead"|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.
</div>
</div>

=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=

See the "EFX Reverb" column of '''[[Fan_Missions_for_The_Dark_Mod|Fan Missions page]]'''. Missions with "Yes" have EFX Reverb.
<br>Most missions use v2.0 presets but a few missions such as "Volta and the Stone" and Behind Closed Doors use v1.0 settings.

=See Also=

The Version 2 definitions were implemented due to [http://bugs.thedarkmod.com/view.php?id=4815 issue 4815], it has some brief explanation.

A tutorial based around EFX can be found [http://forums.thedarkmod.com/topic/19205-getting-started-with-the-efx-room-reverb-system-wip/ here]

An old demonstration map of EAX in TDM is included [http://forums.thedarkmod.com/topic/11045-environmental-audio-extensions-eax-in-tdm/ here]

A discussion about no_efx is [http://forums.thedarkmod.com/topic/19213-efx-discussion here]

The first version of this article was written by Ishtvan [https://forums.thedarkmod.com/index.php?/topic/2071-setting-reverb-data-in-new-soundengine-wiki/ here]

[[Category:Sound]]
[[Category:Tutorial]]

Setting Reverb Data of Rooms (EAX)

2025-01-11T22:01:04Z

Frost Salamander: /* Location Entity Method */

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 [https://github.com/kcat/openal-soft openal-soft]) without any requirements on sound card.

= General =

== Setup ==

EFX for a fan mission can be configured with or without a configuration file. However, fileless configuration is only supported for [[Setting_Reverb_Data_of_Rooms_(EAX)#Presets_(Version_2)|EFX presets]].

== EFX file ==
The EFX info for a map should be stored in the file "<tt>efxs/<mapname>.efx</tt>", 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 "<tt>OpenAL EFX</tt>" in sound settings in the main menu, otherwise TDM won't even try to load the 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:
* <tt>Version 1</tt> was supported by TDM from the very beginning. It uses some non-standard terms and quantities, which makes it hard to work with.
* <tt>Version 2</tt> 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 <tt>reverb</tt> keyword for Version 1 definitions, and <tt>eaxreverb</tt> 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 "<tt>name</tt>" 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 <tt>_area<num></tt> (where <num> is the portal area number), e.g. <tt>_area15</tt>.
'''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 "<tt>reloadSounds</tt>" 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 "<tt>no_efx</tt>" 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 "<tt>reloadDecls</tt>" 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 "<tt>no_efx</tt>" keyword (see issue [http://bugs.thedarkmod.com/view.php?id=4688 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 [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#95 OpenAL Effects Extension Guide](pages 95-101).
The short list is also available in a table on [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#66 page 66 of the guide]:

[[File:Eaxreverb_properties_screenshot.png|500px]]

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

== Presets (Version 2) ==
Presets can be set in 2 ways:
* in the .efx file
* As of TDM 2.13, the '''efx_preset''' spawnarg on the location entity for the location where you want to use the effect.

=== File Method ===

There is one special property <tt>PRESET</tt>, 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.

=== Location Entity Method ===
If using this method, no .efx file is required at all. On the location entity where you want to use the preset, set the spawnarg '''efx_preset''' to the value of the preset. For example:

<pre>
efx_preset CITY_SUBWAY
</pre>

Note that both the configuration file and the location entity spawnargs can be used simultaneously. In the case that both are used to set the preset value for a single location, the spawnarg value will take precedence.

=== Preset Values ===
The presets were taken from OpenAL-Soft implementation which TDM uses.
Here is the full list of preset names:

<pre style="height:350px; overflow:scroll;">
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
</pre>

Their definitions can be seen in [https://github.com/kcat/openal-soft/blob/master/include/AL/efx-presets.h efx-presets.h] from OpenAL-Soft source code.

<div class="mw-collapsible mw-collapsed" data-expandtext="Show" data-collapsetext="Hide">

== 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.

<div class="mw-collapsible-content">

* '''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:

{| style="margin: 0.5em; margin-left: 2em; border: 1px solid #a0a0a0; text-align: right; border-collapse: collapse;" cellpadding="2" border="1"

|-
!bgcolor="#ffdead"|Flag decimal
!bgcolor="#ffdead"|Flag binary
!bgcolor="#ffdead"|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.
</div>
</div>

=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=

See the "EFX Reverb" column of '''[[Fan_Missions_for_The_Dark_Mod|Fan Missions page]]'''. Missions with "Yes" have EFX Reverb.
<br>Most missions use v2.0 presets but a few missions such as "Volta and the Stone" and Behind Closed Doors use v1.0 settings.

=See Also=

The Version 2 definitions were implemented due to [http://bugs.thedarkmod.com/view.php?id=4815 issue 4815], it has some brief explanation.

A tutorial based around EFX can be found [http://forums.thedarkmod.com/topic/19205-getting-started-with-the-efx-room-reverb-system-wip/ here]

An old demonstration map of EAX in TDM is included [http://forums.thedarkmod.com/topic/11045-environmental-audio-extensions-eax-in-tdm/ here]

A discussion about no_efx is [http://forums.thedarkmod.com/topic/19213-efx-discussion here]

The first version of this article was written by Ishtvan [https://forums.thedarkmod.com/index.php?/topic/2071-setting-reverb-data-in-new-soundengine-wiki/ here]

[[Category:Sound]]
[[Category:Tutorial]]

Setting Reverb Data of Rooms (EAX)

2025-01-11T21:05:24Z

Frost Salamander: /* Location Entity Method */

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 [https://github.com/kcat/openal-soft openal-soft]) without any requirements on sound card.

= General =

== Setup ==

EFX for a fan mission can be configured with or without a configuration file. However, fileless configuration is only supported for [[Setting_Reverb_Data_of_Rooms_(EAX)#Presets_(Version_2)|EFX presets]].

== EFX file ==
The EFX info for a map should be stored in the file "<tt>efxs/<mapname>.efx</tt>", 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 "<tt>OpenAL EFX</tt>" in sound settings in the main menu, otherwise TDM won't even try to load the 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:
* <tt>Version 1</tt> was supported by TDM from the very beginning. It uses some non-standard terms and quantities, which makes it hard to work with.
* <tt>Version 2</tt> 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 <tt>reverb</tt> keyword for Version 1 definitions, and <tt>eaxreverb</tt> 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 "<tt>name</tt>" 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 <tt>_area<num></tt> (where <num> is the portal area number), e.g. <tt>_area15</tt>.
'''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 "<tt>reloadSounds</tt>" 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 "<tt>no_efx</tt>" 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 "<tt>reloadDecls</tt>" 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 "<tt>no_efx</tt>" keyword (see issue [http://bugs.thedarkmod.com/view.php?id=4688 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 [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#95 OpenAL Effects Extension Guide](pages 95-101).
The short list is also available in a table on [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#66 page 66 of the guide]:

[[File:Eaxreverb_properties_screenshot.png|500px]]

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

== Presets (Version 2) ==
Presets can be set in 2 ways:
* in the .efx file
* As of TDM 2.13, the '''efx_preset''' spawnarg on the location entity for the location where you want to use the effect.

=== File Method ===

There is one special property <tt>PRESET</tt>, 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.

=== Location Entity Method ===
On the location entity where you want to use the preset, set the spawnarg '''efx_preset''' to the value of the preset. For example:

<pre>
efx_preset CITY_SUBWAY
</pre>

Note that both the configuration file and the location entity spawnargs can be used simultaneously. In the case that both are used to set the preset value for a single location, the spawnarg value will take precedence.

=== Preset Values ===
The presets were taken from OpenAL-Soft implementation which TDM uses.
Here is the full list of preset names:

<pre style="height:350px; overflow:scroll;">
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
</pre>

Their definitions can be seen in [https://github.com/kcat/openal-soft/blob/master/include/AL/efx-presets.h efx-presets.h] from OpenAL-Soft source code.

<div class="mw-collapsible mw-collapsed" data-expandtext="Show" data-collapsetext="Hide">

== 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.

<div class="mw-collapsible-content">

* '''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:

{| style="margin: 0.5em; margin-left: 2em; border: 1px solid #a0a0a0; text-align: right; border-collapse: collapse;" cellpadding="2" border="1"

|-
!bgcolor="#ffdead"|Flag decimal
!bgcolor="#ffdead"|Flag binary
!bgcolor="#ffdead"|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.
</div>
</div>

=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=

See the "EFX Reverb" column of '''[[Fan_Missions_for_The_Dark_Mod|Fan Missions page]]'''. Missions with "Yes" have EFX Reverb.
<br>Most missions use v2.0 presets but a few missions such as "Volta and the Stone" and Behind Closed Doors use v1.0 settings.

=See Also=

The Version 2 definitions were implemented due to [http://bugs.thedarkmod.com/view.php?id=4815 issue 4815], it has some brief explanation.

A tutorial based around EFX can be found [http://forums.thedarkmod.com/topic/19205-getting-started-with-the-efx-room-reverb-system-wip/ here]

An old demonstration map of EAX in TDM is included [http://forums.thedarkmod.com/topic/11045-environmental-audio-extensions-eax-in-tdm/ here]

A discussion about no_efx is [http://forums.thedarkmod.com/topic/19213-efx-discussion here]

The first version of this article was written by Ishtvan [https://forums.thedarkmod.com/index.php?/topic/2071-setting-reverb-data-in-new-soundengine-wiki/ here]

[[Category:Sound]]
[[Category:Tutorial]]

Setting Reverb Data of Rooms (EAX)

2025-01-11T21:03:38Z

Frost Salamander: /* Presets (Version 2) */

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 [https://github.com/kcat/openal-soft openal-soft]) without any requirements on sound card.

= General =

== Setup ==

EFX for a fan mission can be configured with or without a configuration file. However, fileless configuration is only supported for [[Setting_Reverb_Data_of_Rooms_(EAX)#Presets_(Version_2)|EFX presets]].

== EFX file ==
The EFX info for a map should be stored in the file "<tt>efxs/<mapname>.efx</tt>", 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 "<tt>OpenAL EFX</tt>" in sound settings in the main menu, otherwise TDM won't even try to load the 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:
* <tt>Version 1</tt> was supported by TDM from the very beginning. It uses some non-standard terms and quantities, which makes it hard to work with.
* <tt>Version 2</tt> 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 <tt>reverb</tt> keyword for Version 1 definitions, and <tt>eaxreverb</tt> 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 "<tt>name</tt>" 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 <tt>_area<num></tt> (where <num> is the portal area number), e.g. <tt>_area15</tt>.
'''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 "<tt>reloadSounds</tt>" 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 "<tt>no_efx</tt>" 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 "<tt>reloadDecls</tt>" 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 "<tt>no_efx</tt>" keyword (see issue [http://bugs.thedarkmod.com/view.php?id=4688 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 [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#95 OpenAL Effects Extension Guide](pages 95-101).
The short list is also available in a table on [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#66 page 66 of the guide]:

[[File:Eaxreverb_properties_screenshot.png|500px]]

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

== Presets (Version 2) ==
Presets can be set in 2 ways:
* in the .efx file
* As of TDM 2.13, the '''efx_preset''' spawnarg on the location entity for the location where you want to use the effect.

=== File Method ===

There is one special property <tt>PRESET</tt>, 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.

=== Location Entity Method ===
On the location entity where you want to use the preset, set the spawnarg '''efx_preset''' to the value of the preset. For example:

<pre>
efx_preset CITY_SUBWAY
</pre>

Note that both the configuration file and the location entity spawnarg can be used simultaneously. In case that both are set for a single location, the spawnarg value will take precedence.

=== Preset Values ===
The presets were taken from OpenAL-Soft implementation which TDM uses.
Here is the full list of preset names:

<pre style="height:350px; overflow:scroll;">
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
</pre>

Their definitions can be seen in [https://github.com/kcat/openal-soft/blob/master/include/AL/efx-presets.h efx-presets.h] from OpenAL-Soft source code.

<div class="mw-collapsible mw-collapsed" data-expandtext="Show" data-collapsetext="Hide">

== 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.

<div class="mw-collapsible-content">

* '''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:

{| style="margin: 0.5em; margin-left: 2em; border: 1px solid #a0a0a0; text-align: right; border-collapse: collapse;" cellpadding="2" border="1"

|-
!bgcolor="#ffdead"|Flag decimal
!bgcolor="#ffdead"|Flag binary
!bgcolor="#ffdead"|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.
</div>
</div>

=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=

See the "EFX Reverb" column of '''[[Fan_Missions_for_The_Dark_Mod|Fan Missions page]]'''. Missions with "Yes" have EFX Reverb.
<br>Most missions use v2.0 presets but a few missions such as "Volta and the Stone" and Behind Closed Doors use v1.0 settings.

=See Also=

The Version 2 definitions were implemented due to [http://bugs.thedarkmod.com/view.php?id=4815 issue 4815], it has some brief explanation.

A tutorial based around EFX can be found [http://forums.thedarkmod.com/topic/19205-getting-started-with-the-efx-room-reverb-system-wip/ here]

An old demonstration map of EAX in TDM is included [http://forums.thedarkmod.com/topic/11045-environmental-audio-extensions-eax-in-tdm/ here]

A discussion about no_efx is [http://forums.thedarkmod.com/topic/19213-efx-discussion here]

The first version of this article was written by Ishtvan [https://forums.thedarkmod.com/index.php?/topic/2071-setting-reverb-data-in-new-soundengine-wiki/ here]

[[Category:Sound]]
[[Category:Tutorial]]

Setting Reverb Data of Rooms (EAX)

2025-01-11T21:03:11Z

Frost Salamander: /* Location Entity Method */

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 [https://github.com/kcat/openal-soft openal-soft]) without any requirements on sound card.

= General =

== Setup ==

EFX for a fan mission can be configured with or without a configuration file. However, fileless configuration is only supported for [[Setting_Reverb_Data_of_Rooms_(EAX)#Presets_(Version_2)|EFX presets]].

== EFX file ==
The EFX info for a map should be stored in the file "<tt>efxs/<mapname>.efx</tt>", 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 "<tt>OpenAL EFX</tt>" in sound settings in the main menu, otherwise TDM won't even try to load the 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:
* <tt>Version 1</tt> was supported by TDM from the very beginning. It uses some non-standard terms and quantities, which makes it hard to work with.
* <tt>Version 2</tt> 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 <tt>reverb</tt> keyword for Version 1 definitions, and <tt>eaxreverb</tt> 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 "<tt>name</tt>" 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 <tt>_area<num></tt> (where <num> is the portal area number), e.g. <tt>_area15</tt>.
'''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 "<tt>reloadSounds</tt>" 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 "<tt>no_efx</tt>" 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 "<tt>reloadDecls</tt>" 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 "<tt>no_efx</tt>" keyword (see issue [http://bugs.thedarkmod.com/view.php?id=4688 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 [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#95 OpenAL Effects Extension Guide](pages 95-101).
The short list is also available in a table on [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#66 page 66 of the guide]:

[[File:Eaxreverb_properties_screenshot.png|500px]]

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

== Presets (Version 2) ==
Presets can be set in 2 ways:
* in the .efx file
* the efx_preset spawnarg on the location entity for the location where you want to use the effect (since TDM 2.13)

=== File Method ===

There is one special property <tt>PRESET</tt>, 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.

=== Location Entity Method ===
On the location entity where you want to use the preset, set the spawnarg '''efx_preset''' to the value of the preset. For example:

<pre>
efx_preset CITY_SUBWAY
</pre>

Note that both the configuration file and the location entity spawnarg can be used simultaneously. In case that both are set for a single location, the spawnarg value will take precedence.

=== Preset Values ===
The presets were taken from OpenAL-Soft implementation which TDM uses.
Here is the full list of preset names:

<pre style="height:350px; overflow:scroll;">
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
</pre>

Their definitions can be seen in [https://github.com/kcat/openal-soft/blob/master/include/AL/efx-presets.h efx-presets.h] from OpenAL-Soft source code.

<div class="mw-collapsible mw-collapsed" data-expandtext="Show" data-collapsetext="Hide">

== 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.

<div class="mw-collapsible-content">

* '''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:

{| style="margin: 0.5em; margin-left: 2em; border: 1px solid #a0a0a0; text-align: right; border-collapse: collapse;" cellpadding="2" border="1"

|-
!bgcolor="#ffdead"|Flag decimal
!bgcolor="#ffdead"|Flag binary
!bgcolor="#ffdead"|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.
</div>
</div>

=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=

See the "EFX Reverb" column of '''[[Fan_Missions_for_The_Dark_Mod|Fan Missions page]]'''. Missions with "Yes" have EFX Reverb.
<br>Most missions use v2.0 presets but a few missions such as "Volta and the Stone" and Behind Closed Doors use v1.0 settings.

=See Also=

The Version 2 definitions were implemented due to [http://bugs.thedarkmod.com/view.php?id=4815 issue 4815], it has some brief explanation.

A tutorial based around EFX can be found [http://forums.thedarkmod.com/topic/19205-getting-started-with-the-efx-room-reverb-system-wip/ here]

An old demonstration map of EAX in TDM is included [http://forums.thedarkmod.com/topic/11045-environmental-audio-extensions-eax-in-tdm/ here]

A discussion about no_efx is [http://forums.thedarkmod.com/topic/19213-efx-discussion here]

The first version of this article was written by Ishtvan [https://forums.thedarkmod.com/index.php?/topic/2071-setting-reverb-data-in-new-soundengine-wiki/ here]

[[Category:Sound]]
[[Category:Tutorial]]

Setting Reverb Data of Rooms (EAX)

2025-01-11T21:02:31Z

Frost Salamander: /* Location Entity Method */

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 [https://github.com/kcat/openal-soft openal-soft]) without any requirements on sound card.

= General =

== Setup ==

EFX for a fan mission can be configured with or without a configuration file. However, fileless configuration is only supported for [[Setting_Reverb_Data_of_Rooms_(EAX)#Presets_(Version_2)|EFX presets]].

== EFX file ==
The EFX info for a map should be stored in the file "<tt>efxs/<mapname>.efx</tt>", 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 "<tt>OpenAL EFX</tt>" in sound settings in the main menu, otherwise TDM won't even try to load the 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:
* <tt>Version 1</tt> was supported by TDM from the very beginning. It uses some non-standard terms and quantities, which makes it hard to work with.
* <tt>Version 2</tt> 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 <tt>reverb</tt> keyword for Version 1 definitions, and <tt>eaxreverb</tt> 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 "<tt>name</tt>" 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 <tt>_area<num></tt> (where <num> is the portal area number), e.g. <tt>_area15</tt>.
'''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 "<tt>reloadSounds</tt>" 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 "<tt>no_efx</tt>" 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 "<tt>reloadDecls</tt>" 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 "<tt>no_efx</tt>" keyword (see issue [http://bugs.thedarkmod.com/view.php?id=4688 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 [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#95 OpenAL Effects Extension Guide](pages 95-101).
The short list is also available in a table on [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#66 page 66 of the guide]:

[[File:Eaxreverb_properties_screenshot.png|500px]]

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

== Presets (Version 2) ==
Presets can be set in 2 ways:
* in the .efx file
* the efx_preset spawnarg on the location entity for the location where you want to use the effect (since TDM 2.13)

=== File Method ===

There is one special property <tt>PRESET</tt>, 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.

=== Location Entity Method ===
On the location entity where you want to use the preset, set the spawnarg <pre>efx_preset</pre> to the value of the preset. For example:

<pre>
efx_preset CITY_SUBWAY
</pre>

Note that both the configuration file and the location entity spawnarg can be used simultaneously. In case that both are set for a single location, the spawnarg value will take precedence.

=== Preset Values ===
The presets were taken from OpenAL-Soft implementation which TDM uses.
Here is the full list of preset names:

<pre style="height:350px; overflow:scroll;">
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
</pre>

Their definitions can be seen in [https://github.com/kcat/openal-soft/blob/master/include/AL/efx-presets.h efx-presets.h] from OpenAL-Soft source code.

<div class="mw-collapsible mw-collapsed" data-expandtext="Show" data-collapsetext="Hide">

== 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.

<div class="mw-collapsible-content">

* '''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:

{| style="margin: 0.5em; margin-left: 2em; border: 1px solid #a0a0a0; text-align: right; border-collapse: collapse;" cellpadding="2" border="1"

|-
!bgcolor="#ffdead"|Flag decimal
!bgcolor="#ffdead"|Flag binary
!bgcolor="#ffdead"|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.
</div>
</div>

=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=

See the "EFX Reverb" column of '''[[Fan_Missions_for_The_Dark_Mod|Fan Missions page]]'''. Missions with "Yes" have EFX Reverb.
<br>Most missions use v2.0 presets but a few missions such as "Volta and the Stone" and Behind Closed Doors use v1.0 settings.

=See Also=

The Version 2 definitions were implemented due to [http://bugs.thedarkmod.com/view.php?id=4815 issue 4815], it has some brief explanation.

A tutorial based around EFX can be found [http://forums.thedarkmod.com/topic/19205-getting-started-with-the-efx-room-reverb-system-wip/ here]

An old demonstration map of EAX in TDM is included [http://forums.thedarkmod.com/topic/11045-environmental-audio-extensions-eax-in-tdm/ here]

A discussion about no_efx is [http://forums.thedarkmod.com/topic/19213-efx-discussion here]

The first version of this article was written by Ishtvan [https://forums.thedarkmod.com/index.php?/topic/2071-setting-reverb-data-in-new-soundengine-wiki/ here]

[[Category:Sound]]
[[Category:Tutorial]]

Setting Reverb Data of Rooms (EAX)

2025-01-11T21:02:05Z

Frost Salamander: /* Location Entity Method */

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 [https://github.com/kcat/openal-soft openal-soft]) without any requirements on sound card.

= General =

== Setup ==

EFX for a fan mission can be configured with or without a configuration file. However, fileless configuration is only supported for [[Setting_Reverb_Data_of_Rooms_(EAX)#Presets_(Version_2)|EFX presets]].

== EFX file ==
The EFX info for a map should be stored in the file "<tt>efxs/<mapname>.efx</tt>", 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 "<tt>OpenAL EFX</tt>" in sound settings in the main menu, otherwise TDM won't even try to load the 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:
* <tt>Version 1</tt> was supported by TDM from the very beginning. It uses some non-standard terms and quantities, which makes it hard to work with.
* <tt>Version 2</tt> 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 <tt>reverb</tt> keyword for Version 1 definitions, and <tt>eaxreverb</tt> 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 "<tt>name</tt>" 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 <tt>_area<num></tt> (where <num> is the portal area number), e.g. <tt>_area15</tt>.
'''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 "<tt>reloadSounds</tt>" 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 "<tt>no_efx</tt>" 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 "<tt>reloadDecls</tt>" 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 "<tt>no_efx</tt>" keyword (see issue [http://bugs.thedarkmod.com/view.php?id=4688 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 [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#95 OpenAL Effects Extension Guide](pages 95-101).
The short list is also available in a table on [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#66 page 66 of the guide]:

[[File:Eaxreverb_properties_screenshot.png|500px]]

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

== Presets (Version 2) ==
Presets can be set in 2 ways:
* in the .efx file
* the efx_preset spawnarg on the location entity for the location where you want to use the effect (since TDM 2.13)

=== File Method ===

There is one special property <tt>PRESET</tt>, 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.

=== Location Entity Method ===
On the location entity where you want to use the preset, set the spawnarg ''''''efx_preset'''''' to the value of the preset. For example:

<pre>
efx_preset CITY_SUBWAY
</pre>

Note that both the configuration file and the location entity spawnarg can be used simultaneously. In case that both are set for a single location, the spawnarg value will take precedence.

=== Preset Values ===
The presets were taken from OpenAL-Soft implementation which TDM uses.
Here is the full list of preset names:

<pre style="height:350px; overflow:scroll;">
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
</pre>

Their definitions can be seen in [https://github.com/kcat/openal-soft/blob/master/include/AL/efx-presets.h efx-presets.h] from OpenAL-Soft source code.

<div class="mw-collapsible mw-collapsed" data-expandtext="Show" data-collapsetext="Hide">

== 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.

<div class="mw-collapsible-content">

* '''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:

{| style="margin: 0.5em; margin-left: 2em; border: 1px solid #a0a0a0; text-align: right; border-collapse: collapse;" cellpadding="2" border="1"

|-
!bgcolor="#ffdead"|Flag decimal
!bgcolor="#ffdead"|Flag binary
!bgcolor="#ffdead"|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.
</div>
</div>

=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=

See the "EFX Reverb" column of '''[[Fan_Missions_for_The_Dark_Mod|Fan Missions page]]'''. Missions with "Yes" have EFX Reverb.
<br>Most missions use v2.0 presets but a few missions such as "Volta and the Stone" and Behind Closed Doors use v1.0 settings.

=See Also=

The Version 2 definitions were implemented due to [http://bugs.thedarkmod.com/view.php?id=4815 issue 4815], it has some brief explanation.

A tutorial based around EFX can be found [http://forums.thedarkmod.com/topic/19205-getting-started-with-the-efx-room-reverb-system-wip/ here]

An old demonstration map of EAX in TDM is included [http://forums.thedarkmod.com/topic/11045-environmental-audio-extensions-eax-in-tdm/ here]

A discussion about no_efx is [http://forums.thedarkmod.com/topic/19213-efx-discussion here]

The first version of this article was written by Ishtvan [https://forums.thedarkmod.com/index.php?/topic/2071-setting-reverb-data-in-new-soundengine-wiki/ here]

[[Category:Sound]]
[[Category:Tutorial]]

Setting Reverb Data of Rooms (EAX)

2025-01-11T21:01:42Z

Frost Salamander: /* Location Entity Method */

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 [https://github.com/kcat/openal-soft openal-soft]) without any requirements on sound card.

= General =

== Setup ==

EFX for a fan mission can be configured with or without a configuration file. However, fileless configuration is only supported for [[Setting_Reverb_Data_of_Rooms_(EAX)#Presets_(Version_2)|EFX presets]].

== EFX file ==
The EFX info for a map should be stored in the file "<tt>efxs/<mapname>.efx</tt>", 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 "<tt>OpenAL EFX</tt>" in sound settings in the main menu, otherwise TDM won't even try to load the 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:
* <tt>Version 1</tt> was supported by TDM from the very beginning. It uses some non-standard terms and quantities, which makes it hard to work with.
* <tt>Version 2</tt> 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 <tt>reverb</tt> keyword for Version 1 definitions, and <tt>eaxreverb</tt> 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 "<tt>name</tt>" 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 <tt>_area<num></tt> (where <num> is the portal area number), e.g. <tt>_area15</tt>.
'''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 "<tt>reloadSounds</tt>" 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 "<tt>no_efx</tt>" 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 "<tt>reloadDecls</tt>" 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 "<tt>no_efx</tt>" keyword (see issue [http://bugs.thedarkmod.com/view.php?id=4688 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 [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#95 OpenAL Effects Extension Guide](pages 95-101).
The short list is also available in a table on [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#66 page 66 of the guide]:

[[File:Eaxreverb_properties_screenshot.png|500px]]

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

== Presets (Version 2) ==
Presets can be set in 2 ways:
* in the .efx file
* the efx_preset spawnarg on the location entity for the location where you want to use the effect (since TDM 2.13)

=== File Method ===

There is one special property <tt>PRESET</tt>, 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.

=== Location Entity Method ===
On the location entity where you want to use the preset, set the spawnarg '''efx_preset''' ''Italic text''to the value of the preset. For example:

<pre>
efx_preset CITY_SUBWAY
</pre>

Note that both the configuration file and the location entity spawnarg can be used simultaneously. In case that both are set for a single location, the spawnarg value will take precedence.

=== Preset Values ===
The presets were taken from OpenAL-Soft implementation which TDM uses.
Here is the full list of preset names:

<pre style="height:350px; overflow:scroll;">
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
</pre>

Their definitions can be seen in [https://github.com/kcat/openal-soft/blob/master/include/AL/efx-presets.h efx-presets.h] from OpenAL-Soft source code.

<div class="mw-collapsible mw-collapsed" data-expandtext="Show" data-collapsetext="Hide">

== 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.

<div class="mw-collapsible-content">

* '''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:

{| style="margin: 0.5em; margin-left: 2em; border: 1px solid #a0a0a0; text-align: right; border-collapse: collapse;" cellpadding="2" border="1"

|-
!bgcolor="#ffdead"|Flag decimal
!bgcolor="#ffdead"|Flag binary
!bgcolor="#ffdead"|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.
</div>
</div>

=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=

See the "EFX Reverb" column of '''[[Fan_Missions_for_The_Dark_Mod|Fan Missions page]]'''. Missions with "Yes" have EFX Reverb.
<br>Most missions use v2.0 presets but a few missions such as "Volta and the Stone" and Behind Closed Doors use v1.0 settings.

=See Also=

The Version 2 definitions were implemented due to [http://bugs.thedarkmod.com/view.php?id=4815 issue 4815], it has some brief explanation.

A tutorial based around EFX can be found [http://forums.thedarkmod.com/topic/19205-getting-started-with-the-efx-room-reverb-system-wip/ here]

An old demonstration map of EAX in TDM is included [http://forums.thedarkmod.com/topic/11045-environmental-audio-extensions-eax-in-tdm/ here]

A discussion about no_efx is [http://forums.thedarkmod.com/topic/19213-efx-discussion here]

The first version of this article was written by Ishtvan [https://forums.thedarkmod.com/index.php?/topic/2071-setting-reverb-data-in-new-soundengine-wiki/ here]

[[Category:Sound]]
[[Category:Tutorial]]

Setting Reverb Data of Rooms (EAX)

2025-01-11T21:01:20Z

Frost Salamander: /* Location Entity Method */

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 [https://github.com/kcat/openal-soft openal-soft]) without any requirements on sound card.

= General =

== Setup ==

EFX for a fan mission can be configured with or without a configuration file. However, fileless configuration is only supported for [[Setting_Reverb_Data_of_Rooms_(EAX)#Presets_(Version_2)|EFX presets]].

== EFX file ==
The EFX info for a map should be stored in the file "<tt>efxs/<mapname>.efx</tt>", 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 "<tt>OpenAL EFX</tt>" in sound settings in the main menu, otherwise TDM won't even try to load the 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:
* <tt>Version 1</tt> was supported by TDM from the very beginning. It uses some non-standard terms and quantities, which makes it hard to work with.
* <tt>Version 2</tt> 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 <tt>reverb</tt> keyword for Version 1 definitions, and <tt>eaxreverb</tt> 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 "<tt>name</tt>" 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 <tt>_area<num></tt> (where <num> is the portal area number), e.g. <tt>_area15</tt>.
'''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 "<tt>reloadSounds</tt>" 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 "<tt>no_efx</tt>" 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 "<tt>reloadDecls</tt>" 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 "<tt>no_efx</tt>" keyword (see issue [http://bugs.thedarkmod.com/view.php?id=4688 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 [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#95 OpenAL Effects Extension Guide](pages 95-101).
The short list is also available in a table on [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#66 page 66 of the guide]:

[[File:Eaxreverb_properties_screenshot.png|500px]]

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

== Presets (Version 2) ==
Presets can be set in 2 ways:
* in the .efx file
* the efx_preset spawnarg on the location entity for the location where you want to use the effect (since TDM 2.13)

=== File Method ===

There is one special property <tt>PRESET</tt>, 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.

=== Location Entity Method ===
On the location entity where you want to use the preset, set the spawnarg efx_preset to the value of the preset. For example:

<pre>
efx_preset CITY_SUBWAY
</pre>

Note that both the configuration file and the location entity spawnarg can be used simultaneously. In case that both are set for a single location, the spawnarg value will take precedence.

=== Preset Values ===
The presets were taken from OpenAL-Soft implementation which TDM uses.
Here is the full list of preset names:

<pre style="height:350px; overflow:scroll;">
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
</pre>

Their definitions can be seen in [https://github.com/kcat/openal-soft/blob/master/include/AL/efx-presets.h efx-presets.h] from OpenAL-Soft source code.

<div class="mw-collapsible mw-collapsed" data-expandtext="Show" data-collapsetext="Hide">

== 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.

<div class="mw-collapsible-content">

* '''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:

{| style="margin: 0.5em; margin-left: 2em; border: 1px solid #a0a0a0; text-align: right; border-collapse: collapse;" cellpadding="2" border="1"

|-
!bgcolor="#ffdead"|Flag decimal
!bgcolor="#ffdead"|Flag binary
!bgcolor="#ffdead"|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.
</div>
</div>

=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=

See the "EFX Reverb" column of '''[[Fan_Missions_for_The_Dark_Mod|Fan Missions page]]'''. Missions with "Yes" have EFX Reverb.
<br>Most missions use v2.0 presets but a few missions such as "Volta and the Stone" and Behind Closed Doors use v1.0 settings.

=See Also=

The Version 2 definitions were implemented due to [http://bugs.thedarkmod.com/view.php?id=4815 issue 4815], it has some brief explanation.

A tutorial based around EFX can be found [http://forums.thedarkmod.com/topic/19205-getting-started-with-the-efx-room-reverb-system-wip/ here]

An old demonstration map of EAX in TDM is included [http://forums.thedarkmod.com/topic/11045-environmental-audio-extensions-eax-in-tdm/ here]

A discussion about no_efx is [http://forums.thedarkmod.com/topic/19213-efx-discussion here]

The first version of this article was written by Ishtvan [https://forums.thedarkmod.com/index.php?/topic/2071-setting-reverb-data-in-new-soundengine-wiki/ here]

[[Category:Sound]]
[[Category:Tutorial]]

Setting Reverb Data of Rooms (EAX)

2025-01-11T21:00:52Z

Frost Salamander: /* Location Entity Method */

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 [https://github.com/kcat/openal-soft openal-soft]) without any requirements on sound card.

= General =

== Setup ==

EFX for a fan mission can be configured with or without a configuration file. However, fileless configuration is only supported for [[Setting_Reverb_Data_of_Rooms_(EAX)#Presets_(Version_2)|EFX presets]].

== EFX file ==
The EFX info for a map should be stored in the file "<tt>efxs/<mapname>.efx</tt>", 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 "<tt>OpenAL EFX</tt>" in sound settings in the main menu, otherwise TDM won't even try to load the 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:
* <tt>Version 1</tt> was supported by TDM from the very beginning. It uses some non-standard terms and quantities, which makes it hard to work with.
* <tt>Version 2</tt> 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 <tt>reverb</tt> keyword for Version 1 definitions, and <tt>eaxreverb</tt> 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 "<tt>name</tt>" 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 <tt>_area<num></tt> (where <num> is the portal area number), e.g. <tt>_area15</tt>.
'''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 "<tt>reloadSounds</tt>" 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 "<tt>no_efx</tt>" 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 "<tt>reloadDecls</tt>" 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 "<tt>no_efx</tt>" keyword (see issue [http://bugs.thedarkmod.com/view.php?id=4688 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 [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#95 OpenAL Effects Extension Guide](pages 95-101).
The short list is also available in a table on [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#66 page 66 of the guide]:

[[File:Eaxreverb_properties_screenshot.png|500px]]

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

== Presets (Version 2) ==
Presets can be set in 2 ways:
* in the .efx file
* the efx_preset spawnarg on the location entity for the location where you want to use the effect (since TDM 2.13)

=== File Method ===

There is one special property <tt>PRESET</tt>, 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.

=== Location Entity Method ===
On the location entity where you want to use the preset, set the spawnarg efx_preset to the value of the preset. For example:

<pre>
efx_preset CITY_SUBWAY
</pre>

Note that both the configuration file and the location entity spawnarg can be used simultaneously. In this case, the spawnarg value will take precedence.

=== Preset Values ===
The presets were taken from OpenAL-Soft implementation which TDM uses.
Here is the full list of preset names:

<pre style="height:350px; overflow:scroll;">
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
</pre>

Their definitions can be seen in [https://github.com/kcat/openal-soft/blob/master/include/AL/efx-presets.h efx-presets.h] from OpenAL-Soft source code.

<div class="mw-collapsible mw-collapsed" data-expandtext="Show" data-collapsetext="Hide">

== 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.

<div class="mw-collapsible-content">

* '''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:

{| style="margin: 0.5em; margin-left: 2em; border: 1px solid #a0a0a0; text-align: right; border-collapse: collapse;" cellpadding="2" border="1"

|-
!bgcolor="#ffdead"|Flag decimal
!bgcolor="#ffdead"|Flag binary
!bgcolor="#ffdead"|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.
</div>
</div>

=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=

See the "EFX Reverb" column of '''[[Fan_Missions_for_The_Dark_Mod|Fan Missions page]]'''. Missions with "Yes" have EFX Reverb.
<br>Most missions use v2.0 presets but a few missions such as "Volta and the Stone" and Behind Closed Doors use v1.0 settings.

=See Also=

The Version 2 definitions were implemented due to [http://bugs.thedarkmod.com/view.php?id=4815 issue 4815], it has some brief explanation.

A tutorial based around EFX can be found [http://forums.thedarkmod.com/topic/19205-getting-started-with-the-efx-room-reverb-system-wip/ here]

An old demonstration map of EAX in TDM is included [http://forums.thedarkmod.com/topic/11045-environmental-audio-extensions-eax-in-tdm/ here]

A discussion about no_efx is [http://forums.thedarkmod.com/topic/19213-efx-discussion here]

The first version of this article was written by Ishtvan [https://forums.thedarkmod.com/index.php?/topic/2071-setting-reverb-data-in-new-soundengine-wiki/ here]

[[Category:Sound]]
[[Category:Tutorial]]

Setting Reverb Data of Rooms (EAX)

2025-01-11T20:59:20Z

Frost Salamander: /* General */

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 [https://github.com/kcat/openal-soft openal-soft]) without any requirements on sound card.

= General =

== Setup ==

EFX for a fan mission can be configured with or without a configuration file. However, fileless configuration is only supported for [[Setting_Reverb_Data_of_Rooms_(EAX)#Presets_(Version_2)|EFX presets]].

== EFX file ==
The EFX info for a map should be stored in the file "<tt>efxs/<mapname>.efx</tt>", 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 "<tt>OpenAL EFX</tt>" in sound settings in the main menu, otherwise TDM won't even try to load the 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:
* <tt>Version 1</tt> was supported by TDM from the very beginning. It uses some non-standard terms and quantities, which makes it hard to work with.
* <tt>Version 2</tt> 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 <tt>reverb</tt> keyword for Version 1 definitions, and <tt>eaxreverb</tt> 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 "<tt>name</tt>" 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 <tt>_area<num></tt> (where <num> is the portal area number), e.g. <tt>_area15</tt>.
'''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 "<tt>reloadSounds</tt>" 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 "<tt>no_efx</tt>" 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 "<tt>reloadDecls</tt>" 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 "<tt>no_efx</tt>" keyword (see issue [http://bugs.thedarkmod.com/view.php?id=4688 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 [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#95 OpenAL Effects Extension Guide](pages 95-101).
The short list is also available in a table on [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#66 page 66 of the guide]:

[[File:Eaxreverb_properties_screenshot.png|500px]]

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

== Presets (Version 2) ==
Presets can be set in 2 ways:
* in the .efx file
* the efx_preset spawnarg on the location entity for the location where you want to use the effect (since TDM 2.13)

=== File Method ===

There is one special property <tt>PRESET</tt>, 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.

=== Location Entity Method ===
On the location entity where you want to use the preset, set the spawnarg efx_preset to the value of the preset. For example:

<pre>
efx_preset CITY_SUBWAY
</pre>

The presets were taken from OpenAL-Soft implementation which TDM uses.
Here is the full list of preset names:

<pre style="height:350px; overflow:scroll;">
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
</pre>

Their definitions can be seen in [https://github.com/kcat/openal-soft/blob/master/include/AL/efx-presets.h efx-presets.h] from OpenAL-Soft source code.

<div class="mw-collapsible mw-collapsed" data-expandtext="Show" data-collapsetext="Hide">

== 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.

<div class="mw-collapsible-content">

* '''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:

{| style="margin: 0.5em; margin-left: 2em; border: 1px solid #a0a0a0; text-align: right; border-collapse: collapse;" cellpadding="2" border="1"

|-
!bgcolor="#ffdead"|Flag decimal
!bgcolor="#ffdead"|Flag binary
!bgcolor="#ffdead"|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.
</div>
</div>

=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=

See the "EFX Reverb" column of '''[[Fan_Missions_for_The_Dark_Mod|Fan Missions page]]'''. Missions with "Yes" have EFX Reverb.
<br>Most missions use v2.0 presets but a few missions such as "Volta and the Stone" and Behind Closed Doors use v1.0 settings.

=See Also=

The Version 2 definitions were implemented due to [http://bugs.thedarkmod.com/view.php?id=4815 issue 4815], it has some brief explanation.

A tutorial based around EFX can be found [http://forums.thedarkmod.com/topic/19205-getting-started-with-the-efx-room-reverb-system-wip/ here]

An old demonstration map of EAX in TDM is included [http://forums.thedarkmod.com/topic/11045-environmental-audio-extensions-eax-in-tdm/ here]

A discussion about no_efx is [http://forums.thedarkmod.com/topic/19213-efx-discussion here]

The first version of this article was written by Ishtvan [https://forums.thedarkmod.com/index.php?/topic/2071-setting-reverb-data-in-new-soundengine-wiki/ here]

[[Category:Sound]]
[[Category:Tutorial]]

Setting Reverb Data of Rooms (EAX)

2025-01-11T20:58:53Z

Frost Salamander: /* Presets (Version 2) */

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 [https://github.com/kcat/openal-soft openal-soft]) without any requirements on sound card.

= General =

== Setup ==

EFX for an FM can be configured with or without a configuration file. However, fileless configuration is only supported for [[Setting_Reverb_Data_of_Rooms_(EAX)#Presets_(Version_2)|EFX presets]].

== EFX file ==
The EFX info for a map should be stored in the file "<tt>efxs/<mapname>.efx</tt>", 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 "<tt>OpenAL EFX</tt>" in sound settings in the main menu, otherwise TDM won't even try to load the 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:
* <tt>Version 1</tt> was supported by TDM from the very beginning. It uses some non-standard terms and quantities, which makes it hard to work with.
* <tt>Version 2</tt> 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 <tt>reverb</tt> keyword for Version 1 definitions, and <tt>eaxreverb</tt> 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 "<tt>name</tt>" 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 <tt>_area<num></tt> (where <num> is the portal area number), e.g. <tt>_area15</tt>.
'''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 "<tt>reloadSounds</tt>" 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 "<tt>no_efx</tt>" 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 "<tt>reloadDecls</tt>" 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 "<tt>no_efx</tt>" keyword (see issue [http://bugs.thedarkmod.com/view.php?id=4688 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 [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#95 OpenAL Effects Extension Guide](pages 95-101).
The short list is also available in a table on [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#66 page 66 of the guide]:

[[File:Eaxreverb_properties_screenshot.png|500px]]

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

== Presets (Version 2) ==
Presets can be set in 2 ways:
* in the .efx file
* the efx_preset spawnarg on the location entity for the location where you want to use the effect (since TDM 2.13)

=== File Method ===

There is one special property <tt>PRESET</tt>, 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.

=== Location Entity Method ===
On the location entity where you want to use the preset, set the spawnarg efx_preset to the value of the preset. For example:

<pre>
efx_preset CITY_SUBWAY
</pre>

The presets were taken from OpenAL-Soft implementation which TDM uses.
Here is the full list of preset names:

<pre style="height:350px; overflow:scroll;">
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
</pre>

Their definitions can be seen in [https://github.com/kcat/openal-soft/blob/master/include/AL/efx-presets.h efx-presets.h] from OpenAL-Soft source code.

<div class="mw-collapsible mw-collapsed" data-expandtext="Show" data-collapsetext="Hide">

== 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.

<div class="mw-collapsible-content">

* '''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:

{| style="margin: 0.5em; margin-left: 2em; border: 1px solid #a0a0a0; text-align: right; border-collapse: collapse;" cellpadding="2" border="1"

|-
!bgcolor="#ffdead"|Flag decimal
!bgcolor="#ffdead"|Flag binary
!bgcolor="#ffdead"|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.
</div>
</div>

=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=

See the "EFX Reverb" column of '''[[Fan_Missions_for_The_Dark_Mod|Fan Missions page]]'''. Missions with "Yes" have EFX Reverb.
<br>Most missions use v2.0 presets but a few missions such as "Volta and the Stone" and Behind Closed Doors use v1.0 settings.

=See Also=

The Version 2 definitions were implemented due to [http://bugs.thedarkmod.com/view.php?id=4815 issue 4815], it has some brief explanation.

A tutorial based around EFX can be found [http://forums.thedarkmod.com/topic/19205-getting-started-with-the-efx-room-reverb-system-wip/ here]

An old demonstration map of EAX in TDM is included [http://forums.thedarkmod.com/topic/11045-environmental-audio-extensions-eax-in-tdm/ here]

A discussion about no_efx is [http://forums.thedarkmod.com/topic/19213-efx-discussion here]

The first version of this article was written by Ishtvan [https://forums.thedarkmod.com/index.php?/topic/2071-setting-reverb-data-in-new-soundengine-wiki/ here]

[[Category:Sound]]
[[Category:Tutorial]]

Setting Reverb Data of Rooms (EAX)

2025-01-11T20:51:12Z

Frost Salamander: /* Setup */

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 [https://github.com/kcat/openal-soft openal-soft]) without any requirements on sound card.

= General =

== Setup ==

EFX for an FM can be configured with or without a configuration file. However, fileless configuration is only supported for [[Setting_Reverb_Data_of_Rooms_(EAX)#Presets_(Version_2)|EFX presets]].

== EFX file ==
The EFX info for a map should be stored in the file "<tt>efxs/<mapname>.efx</tt>", 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 "<tt>OpenAL EFX</tt>" in sound settings in the main menu, otherwise TDM won't even try to load the 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:
* <tt>Version 1</tt> was supported by TDM from the very beginning. It uses some non-standard terms and quantities, which makes it hard to work with.
* <tt>Version 2</tt> 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 <tt>reverb</tt> keyword for Version 1 definitions, and <tt>eaxreverb</tt> 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 "<tt>name</tt>" 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 <tt>_area<num></tt> (where <num> is the portal area number), e.g. <tt>_area15</tt>.
'''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 "<tt>reloadSounds</tt>" 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 "<tt>no_efx</tt>" 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 "<tt>reloadDecls</tt>" 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 "<tt>no_efx</tt>" keyword (see issue [http://bugs.thedarkmod.com/view.php?id=4688 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 [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#95 OpenAL Effects Extension Guide](pages 95-101).
The short list is also available in a table on [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#66 page 66 of the guide]:

[[File:Eaxreverb_properties_screenshot.png|500px]]

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

== Presets (Version 2) ==

There is one special property <tt>PRESET</tt>, 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:

<pre style="height:350px; overflow:scroll;">
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
</pre>

Their definitions can be seen in [https://github.com/kcat/openal-soft/blob/master/include/AL/efx-presets.h efx-presets.h] from OpenAL-Soft source code.

<div class="mw-collapsible mw-collapsed" data-expandtext="Show" data-collapsetext="Hide">

== 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.

<div class="mw-collapsible-content">

* '''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:

{| style="margin: 0.5em; margin-left: 2em; border: 1px solid #a0a0a0; text-align: right; border-collapse: collapse;" cellpadding="2" border="1"

|-
!bgcolor="#ffdead"|Flag decimal
!bgcolor="#ffdead"|Flag binary
!bgcolor="#ffdead"|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.
</div>
</div>

=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=

See the "EFX Reverb" column of '''[[Fan_Missions_for_The_Dark_Mod|Fan Missions page]]'''. Missions with "Yes" have EFX Reverb.
<br>Most missions use v2.0 presets but a few missions such as "Volta and the Stone" and Behind Closed Doors use v1.0 settings.

=See Also=

The Version 2 definitions were implemented due to [http://bugs.thedarkmod.com/view.php?id=4815 issue 4815], it has some brief explanation.

A tutorial based around EFX can be found [http://forums.thedarkmod.com/topic/19205-getting-started-with-the-efx-room-reverb-system-wip/ here]

An old demonstration map of EAX in TDM is included [http://forums.thedarkmod.com/topic/11045-environmental-audio-extensions-eax-in-tdm/ here]

A discussion about no_efx is [http://forums.thedarkmod.com/topic/19213-efx-discussion here]

The first version of this article was written by Ishtvan [https://forums.thedarkmod.com/index.php?/topic/2071-setting-reverb-data-in-new-soundengine-wiki/ here]

[[Category:Sound]]
[[Category:Tutorial]]

Setting Reverb Data of Rooms (EAX)

2025-01-11T20:49:53Z

Frost Salamander: /* EFX file */

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 [https://github.com/kcat/openal-soft openal-soft]) without any requirements on sound card.

= General =

== Setup ==

EFX for an FM can be configured with or without a configuration file. However, fileless configuration is only supported for EFX presets.

== EFX file ==
The EFX info for a map should be stored in the file "<tt>efxs/<mapname>.efx</tt>", 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 "<tt>OpenAL EFX</tt>" in sound settings in the main menu, otherwise TDM won't even try to load the 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:
* <tt>Version 1</tt> was supported by TDM from the very beginning. It uses some non-standard terms and quantities, which makes it hard to work with.
* <tt>Version 2</tt> 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 <tt>reverb</tt> keyword for Version 1 definitions, and <tt>eaxreverb</tt> 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 "<tt>name</tt>" 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 <tt>_area<num></tt> (where <num> is the portal area number), e.g. <tt>_area15</tt>.
'''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 "<tt>reloadSounds</tt>" 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 "<tt>no_efx</tt>" 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 "<tt>reloadDecls</tt>" 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 "<tt>no_efx</tt>" keyword (see issue [http://bugs.thedarkmod.com/view.php?id=4688 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 [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#95 OpenAL Effects Extension Guide](pages 95-101).
The short list is also available in a table on [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#66 page 66 of the guide]:

[[File:Eaxreverb_properties_screenshot.png|500px]]

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

== Presets (Version 2) ==

There is one special property <tt>PRESET</tt>, 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:

<pre style="height:350px; overflow:scroll;">
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
</pre>

Their definitions can be seen in [https://github.com/kcat/openal-soft/blob/master/include/AL/efx-presets.h efx-presets.h] from OpenAL-Soft source code.

<div class="mw-collapsible mw-collapsed" data-expandtext="Show" data-collapsetext="Hide">

== 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.

<div class="mw-collapsible-content">

* '''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:

{| style="margin: 0.5em; margin-left: 2em; border: 1px solid #a0a0a0; text-align: right; border-collapse: collapse;" cellpadding="2" border="1"

|-
!bgcolor="#ffdead"|Flag decimal
!bgcolor="#ffdead"|Flag binary
!bgcolor="#ffdead"|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.
</div>
</div>

=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=

See the "EFX Reverb" column of '''[[Fan_Missions_for_The_Dark_Mod|Fan Missions page]]'''. Missions with "Yes" have EFX Reverb.
<br>Most missions use v2.0 presets but a few missions such as "Volta and the Stone" and Behind Closed Doors use v1.0 settings.

=See Also=

The Version 2 definitions were implemented due to [http://bugs.thedarkmod.com/view.php?id=4815 issue 4815], it has some brief explanation.

A tutorial based around EFX can be found [http://forums.thedarkmod.com/topic/19205-getting-started-with-the-efx-room-reverb-system-wip/ here]

An old demonstration map of EAX in TDM is included [http://forums.thedarkmod.com/topic/11045-environmental-audio-extensions-eax-in-tdm/ here]

A discussion about no_efx is [http://forums.thedarkmod.com/topic/19213-efx-discussion here]

The first version of this article was written by Ishtvan [https://forums.thedarkmod.com/index.php?/topic/2071-setting-reverb-data-in-new-soundengine-wiki/ here]

[[Category:Sound]]
[[Category:Tutorial]]

Setting Reverb Data of Rooms (EAX)

2025-01-11T20:49:42Z

Frost Salamander: /* Setup */

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 [https://github.com/kcat/openal-soft openal-soft]) without any requirements on sound card.

= General =

== Setup ==

EFX for an FM can be configured with or without a configuration file. However, fileless configuration is only supported for EFX presets.

== 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:
* <tt>Version 1</tt> was supported by TDM from the very beginning. It uses some non-standard terms and quantities, which makes it hard to work with.
* <tt>Version 2</tt> 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 <tt>reverb</tt> keyword for Version 1 definitions, and <tt>eaxreverb</tt> 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 "<tt>name</tt>" 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 <tt>_area<num></tt> (where <num> is the portal area number), e.g. <tt>_area15</tt>.
'''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 "<tt>reloadSounds</tt>" 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 "<tt>no_efx</tt>" 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 "<tt>reloadDecls</tt>" 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 "<tt>no_efx</tt>" keyword (see issue [http://bugs.thedarkmod.com/view.php?id=4688 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 [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#95 OpenAL Effects Extension Guide](pages 95-101).
The short list is also available in a table on [https://usermanual.wiki/Pdf/Effects20Extension20Guide.90272296/view#66 page 66 of the guide]:

[[File:Eaxreverb_properties_screenshot.png|500px]]

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

== Presets (Version 2) ==

There is one special property <tt>PRESET</tt>, 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:

<pre style="height:350px; overflow:scroll;">
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
</pre>

Their definitions can be seen in [https://github.com/kcat/openal-soft/blob/master/include/AL/efx-presets.h efx-presets.h] from OpenAL-Soft source code.

<div class="mw-collapsible mw-collapsed" data-expandtext="Show" data-collapsetext="Hide">

== 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.

<div class="mw-collapsible-content">

* '''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:

{| style="margin: 0.5em; margin-left: 2em; border: 1px solid #a0a0a0; text-align: right; border-collapse: collapse;" cellpadding="2" border="1"

|-
!bgcolor="#ffdead"|Flag decimal
!bgcolor="#ffdead"|Flag binary
!bgcolor="#ffdead"|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.
</div>
</div>

=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=

See the "EFX Reverb" column of '''[[Fan_Missions_for_The_Dark_Mod|Fan Missions page]]'''. Missions with "Yes" have EFX Reverb.
<br>Most missions use v2.0 presets but a few missions such as "Volta and the Stone" and Behind Closed Doors use v1.0 settings.

=See Also=

The Version 2 definitions were implemented due to [http://bugs.thedarkmod.com/view.php?id=4815 issue 4815], it has some brief explanation.

A tutorial based around EFX can be found [http://forums.thedarkmod.com/topic/19205-getting-started-with-the-efx-room-reverb-system-wip/ here]

An old demonstration map of EAX in TDM is included [http://forums.thedarkmod.com/topic/11045-environmental-audio-extensions-eax-in-tdm/ here]

A discussion about no_efx is [http://forums.thedarkmod.com/topic/19213-efx-discussion here]

The first version of this article was written by Ishtvan [https://forums.thedarkmod.com/index.php?/topic/2071-setting-reverb-data-in-new-soundengine-wiki/ here]

[[Category:Sound]]
[[Category:Tutorial]]

What's new in TDM 2.13

2025-01-08T21:05:49Z

Frost Salamander: /* Sound */

{{notreleasedyet|2.13}}
See the [http://bugs.thedarkmod.com/roadmap_page.php roadmap] on our bugtracker.


<br>Source Revision 10920

<br><br>
'''<font size="5">The Dark Mod 2.13 Enhanced AI and GUI Edition!</font>'''
<br>

<font size="3">
<br><br>
A major focus for The Dark Mod 2.13 development cycle was improving how AI see bodies, loot, and other non-player objects.
<br>While our lightgem system is possibly one of the most effective ways to calculate player visibility, it would not be practical
<br>to give all in-game objects, ragdolls, etc their own lightgem calculations. As such, we have historically used a simplified and less
<br>accurate design to determine visibility of non-player items. With 2.13 we reach near parity to the accuracy of the lightgem due to
<br>an improved stochastic sampling system for all objects that an AI can possibly see. ( Thanks stgatilov )
<br>
<br>Now that the AI are more perceptive, why not dull them down again? That is exactly what Amadeus decided and he worked tirelessly on figuring
<br>how to make the "drunken" AI work more reliably and easier to implement for mission authors. Now we have both more and less perceptive AI!
<br>
<br>The long requested Parallax Map feature is now available in TDM! While it was possible to offer this before Doom 3 source was released,
<br>it is quite an expensive effect. With POM integrated into TDM it is now optimized enough for production use. WellingtonCrab has already
<br>created a large set of POM textures ready for inclusion in TDM 2.13 missions!
<br>
<br>Finally, the TDM community restarted it's perennial debate about how mission names should be displayed and sorted in the mission list.
<br>Previously, there was a compromise where the missions would display naturally but would be sorted ignoring "the" and "a" in the title.
<br>This was the status quo for quite some time but players have emerged to request that we revert to "Mission Name, The" in the GUI.
<br>Daft Mugi solved this by creating a toggle that allows either sorting style. He also made the whole debate pretty much moot by implementing
<br>a search window so you can easily find the desired mission by typing all or part of it's name! Mission management is has never been smoother!
<br><br><br>

'''See our [https://forums.thedarkmod.com/index.php?/topic/22641-213-feature-discussion-threads/ Feature Discuss Threads] for more details about substantial changes.'''

</font>

----
<br><br>

== <br><br> <font size="4">'''Important CVARS''' ==

=== <font size="4">PLAYER</font> ===
<br>
tdm_holdfrob_* --- set of variables that affect the reworked frob controls.

tdm_autosearch_bodies --- automatically take items attached to unconscious bodies on frob.

pm_headbob_mod, pm_lean_* --- allows for the reduction of some player movements.

{{clear}}

=== <font size="4">HELPER</font> ===
<br>

tdm_show_viewpos, screenshot_viewpos --- embedding viewpos into screenshots for better bug reports.

tdm_open_doors, tdm_close_doors --- cheats to make mission testing faster.

{{clear}}

=== <font size="4">TROUBLESHOOTING</font> ===
<br>

g_lightQuotientAlgo 0 ( revert to the old AI vision system )

jobs_numThreadsRealtime 2 ( force 2 threads )

r_subviewMaxDepth 1 ( no subview recursion )

r_skipParallax 1 ( disable POM effect )

r_envmapBumpyBehavior 0 ( revert to old environment map behavior )

{{clear}}
<br>

== '''Graphics''' ==

* Parallax Occlusion Mapping support ( See [https://forums.thedarkmod.com/index.php?/topic/22574-experimental-support-of-parallax-mapping-in-213/ thread] )
* Environment mapped textures with bumpmaps now properly respond to stage keywords ( See [https://forums.thedarkmod.com/index.php?/topic/22402-213-environment-mapping-bumpmap/ thread] )
* Nested subviews (mirrors, remotes, sky, etc.) now work properly (6434).
* Fixed rendering of volumetric light and particles in X-ray views and mirrors (6538).
* Shadow Map specific features are enabled by default in "Maps" mode ( alpha tested shadows, etc)
* Minor change in shadow map acne / blur radius computation (6571).
* Tonemapping has been altered to improve appearance of overly bright colors. Such colors are no longer clamped at value = 1 and they desaturate at high brightness. Finally, brightness slider should be much more useful now ( [https://forums.thedarkmod.com/index.php?/topic/22600-tone-mapping/page/2/#findComment-498990 post] ).
* Refactored the "HeatHaze" shaders so that one shader can produce multiple variations via parameters
* Disabled texture compression for light images: falloff and IBL cubemaps.
* Fixed light culling bug on elongated models with non-identity rotation (6557).
{{clear}}
<br>

== '''AI''' ==

* AI now have a more accurate vision system ( see [https://forums.thedarkmod.com/index.php?/topic/22639-213-ai-vision-uses-different-light-estimate-system/ thread] )
* Major improvements in drunk AIs: setting "drunk" spawnarg is enough now; new sounds, animation improvements, greetings, etc. (6507). Fixed drunk women AI (5047).

{{clear}}
<br>

== '''Mapping''' ==

* Added improved editor images for textures/darkmod/metal/detailed materials (6575)
* Added editor spawnarg for "parallelsky" (6496)
* Added "particle collision-ready" weather materials (6545)
* Added min/max builtin functions to game scripts.
* Added script events about gravity, health, in-air movement.
* Added script events setUserBy, setFrobActionScript.
* Added "distance_follower_reached", "distance_follower_catchup_distance" and "distance_follower_stop_running" spawnargs allowing mappers to customize AI follower distances (6552)
* Added "def_vocal_set_drunk" spawnarg to allow mappers to specify which drunk vocal set an AI should use (6507).
* Added "idle_bark_interval_max_drunk" "idle_bark_interval_min_drunk" spawnargs allowing mappers to customize drunk bark intervals (6507).
* Added "snd_greeting_generic_drunk" spawnarg for drunk AI (6507)
* Added cm_allocator debug cvar (6505).
* Added r_lockView debug rendering cvar ( [https://forums.thedarkmod.com/index.php?/topic/22388-r_lockview-debug-cvar/ thread] ).
* Added proper dmap error message if map file contains an entity before worldspawn.
* Fixed dmap making almost axis-aligned visportals buggy (6480)

{{clear}}

== '''Coding''' ==

* Auto-detect number of parallel threads to use in jobs system (6503)
* Vsync now properly works on Linux
* FPS limit code has been improved
* Level loading is further accelerated with better utilization of multicore CPUs and parallel loading of sound samples.
* CVAR system has been made fully thread safe
* Missions can now safely override CVAR values via config or script operations
* The system for third-party dependencies has been moved to Conan 2 and extended. Now the CI server regularly builds TDM and its dependencies completely from source code.
* Deleted a lot of old rendering code under useNewRenderPasses + some cleanup (6271).
* Core missions are now stored uncompressed in assets SVN (6498).
* Optimization: don't render interaction groups with black diffuse & specular.
{{clear}}
<br>

== '''Assets''' ==

* Added several parallax materials, as well as their non-parallax equivalents
* Added 17 modular industrial pipe models from Polyhaven
* Added combined lampion light entity
* Added several factory_machines models (6537)
* Added textures/darkmod/decals/distant_cityscape_01_tiling material (6487)
* Added missing normalmap to stainglass_saint_03 (6521)
* Added missing textures for rough_boards_scratched material (4157)
* Added [[Creating_textures_from_Ornate_Photos|ornate]] wood/panels/mary_panel texture
* Added [[Creating_textures_from_Ornate_Photos|ornate]] stone/sculpted/girard_relief texture
* Added colored versions of gen3 environment cubemaps for metallic materials.
* Added new environment cubemaps: sparkles, studio, blurry.
* Added skybox materials clouds3 and clouds_4_small + prefabs.
* Fixed several issues with largesquare01 window textures (6579)
* Fixed broken material for stove_open02.lwo (6580)
* Fixed floating decals for ext_timber01_window01.lwo (5782)
* Fixed gaps in mesh and UV for generator_big.lwo and warehouse_front_doorframe.lwo (6581)
* Fixed broken UV for longbanner_ragged.lwo (6573)
* Fixed issues with newspaper01.lwo (6568)
* Fixed normal map of ornament_relief_mold_eaglelshield (6585).
* Fixed handle_curved02_latch prefab, deleted pull_handle (6286).
* Improved "scepter" material ( [https://forums.thedarkmod.com/index.php?/topic/22586-better-looking-metals-in-darkmod/page/4/#comment-498297 thread] ).

{{clear}}
<br>

== '''Gameplay and Interaction''' ==

* Updated Training Mission with Vine Arrow tutorial, graphics enhancements, and EFX Reverb
* Added entityDef archery_target01 with hit detection, it is now used in Training Mission.
* Added gas mine playertool
* Added slowfall potion
* Added invisibility potion by Kingsal
* Fixed frob interaction with candle holder that's initially extinguished (6577).
* Improved lightgem calculations while leaning ( [https://forums.thedarkmod.com/index.php?/topic/22587-bug-lean-light-calculation/#comment-498247 post] ).

{{clear}}
<br>

== '''GUIs''' ==

* Massive improvements in mission select & download menus, added search (6339 6570 6449).
* Loading progress bar has been re-implemented to reflect all the loading optimizations of the past years.
* Mission Notes ( readme data ) can now be scrolled
* Mission Debriefing feature ( See [https://forums.thedarkmod.com/index.php?/topic/21831-support-for-gui-based-debrief/ thread] )
* Stone font improvements
* Reduced font size of mission list, which allows to see more missions and longer names
* Texture Quality option for lowend players
* Added TDM version + engine revision in lower-left corner of main menu.
* Increased size of secret message overlay GUI.
* Fixed map immobilization not applied if opening map with inv use key.
* Forbid adding missions to download when download is in progress (6368).

{{clear}}
<br>

== '''Sound''' ==

* EFX reverb presets can now be set on location entities using the '''efx_preset''' spawnarg, rather than requiring an .efx file (6273).
* Fixed sleeping sounds for drunk AIs (6539), and other sounds for them too (6507).
* Added improved footstep sounds for broken glass and ice material surfaces (6551).
* Fixed water_medium_running soundshader (5384)
* Subtitles volume estimation is much better now, subtitles for too quiet sounds are no longer shown. Visual appearance of the subtitles font has been greatly improved.
* Added two drunk AI vocalsets voiced by Goldwell and Bikerdude: Drunk Moor and Drunk Jack

{{clear}}

{{whatsnew|sort=213}}

What's new in TDM 2.13

2025-01-08T20:59:52Z

Frost Salamander: /* Sound */

{{notreleasedyet|2.13}}
See the [http://bugs.thedarkmod.com/roadmap_page.php roadmap] on our bugtracker.


<br>Source Revision 10920

<br><br>
'''<font size="5">The Dark Mod 2.13 Enhanced AI and GUI Edition!</font>'''
<br>

<font size="3">
<br><br>
A major focus for The Dark Mod 2.13 development cycle was improving how AI see bodies, loot, and other non-player objects.
<br>While our lightgem system is possibly one of the most effective ways to calculate player visibility, it would not be practical
<br>to give all in-game objects, ragdolls, etc their own lightgem calculations. As such, we have historically used a simplified and less
<br>accurate design to determine visibility of non-player items. With 2.13 we reach near parity to the accuracy of the lightgem due to
<br>an improved stochastic sampling system for all objects that an AI can possibly see. ( Thanks stgatilov )
<br>
<br>Now that the AI are more perceptive, why not dull them down again? That is exactly what Amadeus decided and he worked tirelessly on figuring
<br>how to make the "drunken" AI work more reliably and easier to implement for mission authors. Now we have both more and less perceptive AI!
<br>
<br>The long requested Parallax Map feature is now available in TDM! While it was possible to offer this before Doom 3 source was released,
<br>it is quite an expensive effect. With POM integrated into TDM it is now optimized enough for production use. WellingtonCrab has already
<br>created a large set of POM textures ready for inclusion in TDM 2.13 missions!
<br>
<br>Finally, the TDM community restarted it's perennial debate about how mission names should be displayed and sorted in the mission list.
<br>Previously, there was a compromise where the missions would display naturally but would be sorted ignoring "the" and "a" in the title.
<br>This was the status quo for quite some time but players have emerged to request that we revert to "Mission Name, The" in the GUI.
<br>Daft Mugi solved this by creating a toggle that allows either sorting style. He also made the whole debate pretty much moot by implementing
<br>a search window so you can easily find the desired mission by typing all or part of it's name! Mission management is has never been smoother!
<br><br><br>

'''See our [https://forums.thedarkmod.com/index.php?/topic/22641-213-feature-discussion-threads/ Feature Discuss Threads] for more details about substantial changes.'''

</font>

----
<br><br>

== <br><br> <font size="4">'''Important CVARS''' ==

=== <font size="4">PLAYER</font> ===
<br>
tdm_holdfrob_* --- set of variables that affect the reworked frob controls.

tdm_autosearch_bodies --- automatically take items attached to unconscious bodies on frob.

pm_headbob_mod, pm_lean_* --- allows for the reduction of some player movements.

{{clear}}

=== <font size="4">HELPER</font> ===
<br>

tdm_show_viewpos, screenshot_viewpos --- embedding viewpos into screenshots for better bug reports.

tdm_open_doors, tdm_close_doors --- cheats to make mission testing faster.

{{clear}}

=== <font size="4">TROUBLESHOOTING</font> ===
<br>

g_lightQuotientAlgo 0 ( revert to the old AI vision system )

jobs_numThreadsRealtime 2 ( force 2 threads )

r_subviewMaxDepth 1 ( no subview recursion )

r_skipParallax 1 ( disable POM effect )

r_envmapBumpyBehavior 0 ( revert to old environment map behavior )

{{clear}}
<br>

== '''Graphics''' ==

* Parallax Occlusion Mapping support ( See [https://forums.thedarkmod.com/index.php?/topic/22574-experimental-support-of-parallax-mapping-in-213/ thread] )
* Environment mapped textures with bumpmaps now properly respond to stage keywords ( See [https://forums.thedarkmod.com/index.php?/topic/22402-213-environment-mapping-bumpmap/ thread] )
* Nested subviews (mirrors, remotes, sky, etc.) now work properly (6434).
* Fixed rendering of volumetric light and particles in X-ray views and mirrors (6538).
* Shadow Map specific features are enabled by default in "Maps" mode ( alpha tested shadows, etc)
* Minor change in shadow map acne / blur radius computation (6571).
* Tonemapping has been altered to improve appearance of overly bright colors. Such colors are no longer clamped at value = 1 and they desaturate at high brightness. Finally, brightness slider should be much more useful now ( [https://forums.thedarkmod.com/index.php?/topic/22600-tone-mapping/page/2/#findComment-498990 post] ).
* Refactored the "HeatHaze" shaders so that one shader can produce multiple variations via parameters
* Disabled texture compression for light images: falloff and IBL cubemaps.
* Fixed light culling bug on elongated models with non-identity rotation (6557).
{{clear}}
<br>

== '''AI''' ==

* AI now have a more accurate vision system ( see [https://forums.thedarkmod.com/index.php?/topic/22639-213-ai-vision-uses-different-light-estimate-system/ thread] )
* Major improvements in drunk AIs: setting "drunk" spawnarg is enough now; new sounds, animation improvements, greetings, etc. (6507). Fixed drunk women AI (5047).

{{clear}}
<br>

== '''Mapping''' ==

* Added improved editor images for textures/darkmod/metal/detailed materials (6575)
* Added editor spawnarg for "parallelsky" (6496)
* Added "particle collision-ready" weather materials (6545)
* Added min/max builtin functions to game scripts.
* Added script events about gravity, health, in-air movement.
* Added script events setUserBy, setFrobActionScript.
* Added "distance_follower_reached", "distance_follower_catchup_distance" and "distance_follower_stop_running" spawnargs allowing mappers to customize AI follower distances (6552)
* Added "def_vocal_set_drunk" spawnarg to allow mappers to specify which drunk vocal set an AI should use (6507).
* Added "idle_bark_interval_max_drunk" "idle_bark_interval_min_drunk" spawnargs allowing mappers to customize drunk bark intervals (6507).
* Added "snd_greeting_generic_drunk" spawnarg for drunk AI (6507)
* Added cm_allocator debug cvar (6505).
* Added r_lockView debug rendering cvar ( [https://forums.thedarkmod.com/index.php?/topic/22388-r_lockview-debug-cvar/ thread] ).
* Added proper dmap error message if map file contains an entity before worldspawn.
* Fixed dmap making almost axis-aligned visportals buggy (6480)

{{clear}}

== '''Coding''' ==

* Auto-detect number of parallel threads to use in jobs system (6503)
* Vsync now properly works on Linux
* FPS limit code has been improved
* Level loading is further accelerated with better utilization of multicore CPUs and parallel loading of sound samples.
* CVAR system has been made fully thread safe
* Missions can now safely override CVAR values via config or script operations
* The system for third-party dependencies has been moved to Conan 2 and extended. Now the CI server regularly builds TDM and its dependencies completely from source code.
* Deleted a lot of old rendering code under useNewRenderPasses + some cleanup (6271).
* Core missions are now stored uncompressed in assets SVN (6498).
* Optimization: don't render interaction groups with black diffuse & specular.
{{clear}}
<br>

== '''Assets''' ==

* Added several parallax materials, as well as their non-parallax equivalents
* Added 17 modular industrial pipe models from Polyhaven
* Added combined lampion light entity
* Added several factory_machines models (6537)
* Added textures/darkmod/decals/distant_cityscape_01_tiling material (6487)
* Added missing normalmap to stainglass_saint_03 (6521)
* Added missing textures for rough_boards_scratched material (4157)
* Added [[Creating_textures_from_Ornate_Photos|ornate]] wood/panels/mary_panel texture
* Added [[Creating_textures_from_Ornate_Photos|ornate]] stone/sculpted/girard_relief texture
* Added colored versions of gen3 environment cubemaps for metallic materials.
* Added new environment cubemaps: sparkles, studio, blurry.
* Added skybox materials clouds3 and clouds_4_small + prefabs.
* Fixed several issues with largesquare01 window textures (6579)
* Fixed broken material for stove_open02.lwo (6580)
* Fixed floating decals for ext_timber01_window01.lwo (5782)
* Fixed gaps in mesh and UV for generator_big.lwo and warehouse_front_doorframe.lwo (6581)
* Fixed broken UV for longbanner_ragged.lwo (6573)
* Fixed issues with newspaper01.lwo (6568)
* Fixed normal map of ornament_relief_mold_eaglelshield (6585).
* Fixed handle_curved02_latch prefab, deleted pull_handle (6286).
* Improved "scepter" material ( [https://forums.thedarkmod.com/index.php?/topic/22586-better-looking-metals-in-darkmod/page/4/#comment-498297 thread] ).

{{clear}}
<br>

== '''Gameplay and Interaction''' ==

* Updated Training Mission with Vine Arrow tutorial, graphics enhancements, and EFX Reverb
* Added entityDef archery_target01 with hit detection, it is now used in Training Mission.
* Added gas mine playertool
* Added slowfall potion
* Added invisibility potion by Kingsal
* Fixed frob interaction with candle holder that's initially extinguished (6577).
* Improved lightgem calculations while leaning ( [https://forums.thedarkmod.com/index.php?/topic/22587-bug-lean-light-calculation/#comment-498247 post] ).

{{clear}}
<br>

== '''GUIs''' ==

* Massive improvements in mission select & download menus, added search (6339 6570 6449).
* Loading progress bar has been re-implemented to reflect all the loading optimizations of the past years.
* Mission Notes ( readme data ) can now be scrolled
* Mission Debriefing feature ( See [https://forums.thedarkmod.com/index.php?/topic/21831-support-for-gui-based-debrief/ thread] )
* Stone font improvements
* Reduced font size of mission list, which allows to see more missions and longer names
* Texture Quality option for lowend players
* Added TDM version + engine revision in lower-left corner of main menu.
* Increased size of secret message overlay GUI.
* Fixed map immobilization not applied if opening map with inv use key.
* Forbid adding missions to download when download is in progress (6368).

{{clear}}
<br>

== '''Sound''' ==

* EFX reverb presets can now be set on location entities using a spawnarg, rather than requiring an .efx file (6273).
* Fixed sleeping sounds for drunk AIs (6539), and other sounds for them too (6507).
* Added improved footstep sounds for broken glass and ice material surfaces (6551).
* Fixed water_medium_running soundshader (5384)
* Subtitles volume estimation is much better now, subtitles for too quiet sounds are no longer shown. Visual appearance of the subtitles font has been greatly improved.
* Added two drunk AI vocalsets voiced by Goldwell and Bikerdude: Drunk Moor and Drunk Jack

{{clear}}

{{whatsnew|sort=213}}

User:Frost Salamander

2024-12-24T10:24:49Z

Frost Salamander:

== TDM Files and Contents ==

{| class="wikitable"
|+ Caption text
|-
! Content !! File path !! Notes
|-
| Skins || tdm_models_decls01.pk4\skins || skin files shipped with TDM
|-
| Script Constants|| tdm_base01.pk4\script\tdm_defs.script || constant values. Useful if you need to know the literal values for use in your scripts.
|-
| Script Objects|| tdm_base01.pk4\script || various script objects for entities.
|-
| tdm_ai_humanoid_newskel.def || tdm_ai_humanoid_undead01.pk4\def\tdm_ai_humanoid_newskel.def || Base class for all TDM humanoid entities
|-
| GUI Icons || tdm_gui01.pk4\dds\guis\assets\hud\ || HUD icons. e.g. loot, potions, etc
|-
| sound shaders || tdm_sound_ambient_decls01.pk4\sound || ambient environmental sound shaders
|-
| materials definitions || tdm_textures_base01.pk4\materials || base materials files
|-
| guard model materials || tdm_ai_humanoid_guards01.pk4 || guard materials and texture files
|-
| Stim types || tdm_base01.pk4/script/tdm_stim_response.script ||
|-
| Readable textures || tdm_gui01.pk4/dds/guis/assets/readables || various parchment textures
|-
| Blueprint textures || tdm_models02.pk4 || textures/readables/blueprint01*
|-
| Light textures || tdm_textures_base01.pk4 || In both /lights and textures/lights
|}

== Creating an Image Decal with Gimp ==
# Go to somewhere like pixabay.com and search for free images. I usually filter by 'vector graphics' (e.g. PNG) because it supports alpha channel which you'll need for decals.
# Once you find an image, download it. I tend to get medium-sized versions (e.g. close to 1024 x 1024)
# Open the file in Gimp
# Scale the image to 1024x1024 pixels.
# export as TGA

== Creating a Text Decal with Gimp ==
# Open Gimp - New ->
# Set image size to 1024 x 1024 (or something more rectangular like 1024 x 512)
# Click Advanced -> Fill with: transparency
# Add text layer
# When happy with text, right-click the text layer and 'merge down' into alpha layer
# save and export as TGA.
# Create a materials file (.mtr) like so:

textures/darkmod/decals/signs/coronet
{
DECAL_MACRO
noimpact

{
blend blend
map textures/darkmod/decals/signs/coronet
}
}

== Creating a material using existing images (e.g. from textures.com) using GIMP ==

'''Written on May 28th, 2023 using GIMP 2.10.34'''

This will describe how to create your own texture (material) using an image found on the internet. I will use textures.com as an example.

'''Ensure that the license for whatever source you use is appropriate for TDM (e.g. allows use in video games)'''

We will end up with 3 image files and one materials file:
* diffuse map (the base image with colour details, etc)
* normal map (faked bump/dent data)
* DarkRadiant editor icon

This doesn't cover creation of a specular map. This isn't needed unless your material needs a shiny surface (e.g. metal or wet surfaces).

=== Obtain your image ===
# Log into textures.com and find an image you like under the 'Regular Photos' section ('''NOT''' 'Special Content'). Make sure it's seamless if it needs to be tiled/repeatable (e.g. for bricks or walls). If it's something like a door or window, it doesn't need to be seamless. There is normally a JPG format that that is close to or exactly 1024x1024 pixels. Download it.

=== Open your Image in GIMP ===
The first thing you may see here is a pop-up asking if you want to convert the image to 'the built-in sRGB color profile'. I'm not sure the implications of doing this but just choose 'Convert'. '''(ADVICE NEEDED)'''

=== Resize Image (if needed) ===
TDM standard resolution for textures is 1024 x 1024. However it's possible to get away with 2048 x 2048 at the cost of file size and performance.
If you can't find a 1024 x 1024 image for whatever reason (say it's 4K instead), you can scale it down:
# With the image open in GIMP, click Image -> Scale Image...
# Set the width in 'Image Size' in pixels to 1024. Make sure the width and height are 'chained' (the little link icon should be whole). The height will then scale down proportionately to match the width.

=== Crop your Image ===
This is only needed if you don't intend to use the entire image as-is (e.g. if you want to cut a door or window out of an image). Skip this section if that is not the case.
# With the image in GIMP, select the Crop Tool (Shift+C).
# Under the 'Tool Options' tab, tick the box for 'Delete cropped pixels'
# Using the crop tool select the area you want to keep on the image with your mouse, and press 'Enter' when done.

=== Create the Diffuse Map (DDS File) ===
# With the original or cropped image open in GIMP Choose File -> Export as...
# In the next popup, change the filename to 'texturename.dds' and click 'Export'.
# On the next pop-up, choose your compression format (see below) and select 'Generate mipmaps'. Under 'Mipmap Options' choose 'Filter': 'Kaiser' for best quality. Click 'Export'
- Compression:
- if your image contains an alpha channel, choose 'BC3 / DXT5'
- if your image does not contain an alpha channel, choose 'BC1 / DXT1'

=== Create the Normal Map (TGA File)===
Apart from creating the normal map, the point of the first few steps is to reduce the amount of 'noise' in the image which can lead to a grainy appearance.
# With the original or cropped image open in GIMP, select Colors -> Desaturate -> Desaturate. Click 'OK'
# Select Filters -> Blur -> Gaussian Blur. Leave the defaults and click 'OK'.
# Select Colors -> Curves and adjust the curve to 'wash out' (i.e. brighten) the image to remove any noise detail.
# Select Filters -> Generic -> Normal Map..
# The image will change to a blueish colour and you will be able to see the 'bumps'. The only thing I adjust here is the 'Scale' property. If it looks very grainy, just reduce the scale. For things like bricks, I use a value < 5 or else the finished texture will look very grainy in TDM. For stuff like doors, a value of about 10 looks OK.
# After adjusting the scale, click 'OK'
# Choose File -> Export as..., change the file name to 'texturename_local.tga' and click 'Export'
# On the next pop-up, untick 'RLE compression' and leave 'Origin' at 'Bottom left'. Click 'Export'. '''(ADVICE NEEDED)'''

=== Create the editor icon (JPG File) ===
# Since you've modified the image, either close and re-open the image in GIMP, or go back into your Undo History and select the original image (or cropped image if it's been cropped).
# Choose Image -> Scale Image... from the menu.
# On the dialogue, either scale it to 256x256 px (if it was a 1024x1024 image originally), or just scale it down to 25% if it was something else. Click 'Scale'. If the image looks too blurry, you can try 512 x 512.
# Choose File -> Export as..., change the file name to 'texturename_ed.jpg' and click 'Export'
# On the next pop-up, untick all the 'save data' boxes except for 'Save color profile' '''(ADVICE NEEDED)'''. Click 'Export'

=== Create TDM materials file ===
# Within your FM folder, save all your images in the appropriate TDM folder structure. Just follow the existing conventions. For example your DDS files go into 'dds/textures/darkmod/stone/brick' and your normal map and editor files go into 'textures/darkmod/stone/brick'
# Create the materials file as follows below. Give it a name like 'mybricks.mtr' and put it in the /materials folder in your FM. The material name as it appears in DarkRadiant appears at the top.

'''NOTE''': 'texturename' in this example is 'bricks_dirty'
textures/darkmod/stone/brick/bricks_dirty
{
stone
description "vine_friendly"

qer_editorimage textures/darkmod/stone/brick/bricks_dirty_ed
diffusemap textures/darkmod/stone/brick/bricks_dirty
bumpmap textures/darkmod/stone/brick/bricks_dirty_local
}