Editing EDF sound reference

==Sounds==
The [[EDF]] '''Sound''' block defines sounds to be used in the game. They are linked to the sound lumps included in wads, and the default Doom and Heretic entries have the same names as the lumps, minus the DS prefix (for Doom).
{{backto|EDF}}

===Syntax===
 sound <mnemonic>
 {
   lump           <string>
   prefix         <boolean>
   singularity    <singularity class>
   priority       <number>
   link           <sound mnemonic>
   alias          <sound mnemonic>
   random         <sound mnemonic list>
   skinindex      <skin index type>
   linkvol        <number>
   linkpitch      <number>
   clipping_dist  <number>
   close_dist     <number>
   pitchvariance  <pitch variance type>
   subchannel     <subchannel class>
   pcslump        <string>
   nopcsound      <boolean>
   dehackednum    <number>
 }
===Fields===
*'''lump'''
:The <code>lump</code> field indicates the lump name that this sound resource will have in WAD or PKE files. If the <code>prefix</code> field below is <code>true</code>, the prefix "DS" will be appended to this name when looking for the sound. Otherwise, this name will be used exactly as it is provided. In the event a sound is not found, a default sound for the current game mode (DSPISTOL in DOOM, GLDHIT in Heretic) will be played instead.
:If you use [[PKE]] archives and the sound name is longer than 8 characters, you ''must'' use the long file name format. The long file name is done by the following rules:
:*/ (slash) ''must'' be added at the beginning of the path.
:*The full path, including extension, inside the PKE must be used.
:*It must be lowercase, even if it has different capitalization in the PKE.
:*It is mandatory to put quotes around the path.
:Long file name example: <code>lump "/sounds/soundname1.snd"</code> for a sound file of <code>sounds/SoundName1.snd</code> inside the PKE archive.
:If a value is not provided to this field, then this sound's mnemonic will be copied directly to this field. In this case, the default value for the <code>prefix</code> field becomes <code>true</code>. This means that the mnemonic will be prefixed with the "DS" prefix to construct the final sound lump name. If an explicit value is provided to this field, then the default value of the prefix field becomes <code>false</code>. This means the lump name, as provided, becomes the final sound lump name and will not be prefixed in any way. 
*'''prefix'''
:Default = Depends on presence of lump field
:This boolean field indicates whether to prefix the lump name with DS when searching for this sound's lump. Values of false/no/off mean that the lump will not be prefixed. Values of true/yes/on mean that it should be prefixed. If the lump field is provided, the default value of this field changes from true to false.
*'''singularity'''
:Default = ''sg_none''
:This field indicates a singularity class for this sound. If another sound of the same singularity class is playing when this sound is played, the former will be stopped. This is used to implement appropriate player sound behavior in an extensible and modifiable manner. The possible values for the singularity class are as follows: 
:*sg_none
:*sg_itemup
:*sg_wpnup
:*sg_oof
:*sg_getpow
*'''priority'''
:Default = 64
:This field establishes a relative priority for this sound. When sounds must be stopped in order to start new ones, those with the lowest priority will be replaced first. Priority scales down with distance, so sounds playing at higher volume or closer to the player have priority over quieter and more distant sounds. Please note carefully that a higher value in this field means a lower priority. So 0 is the highest priority possible, and 255 is the lowest priority (priorities lower than 255 will be capped into range).
*'''link'''
:Default = "none"
:This field links this sound definition to another existing sound definition. Its value must either be "none," or another valid sound mnemonic. When a linked sound is played, the sound that is linked to will be played instead, using the linkvol and linkpitch parameters provided in this sound entry. All parameters for playing the sound, including priority, singularity, pitch variance, and clipping distances come from this sound definition, and not from the sound to which this one is linked.
*'''alias'''
:Default = "none"
:This field causes this sound definition to become an alias for another existing sound. Its value must either be "none," or another valid sound mnemonic. When this sound is played, the aliased sound will be played instead, using all the data defined in the aliased sound (when an alias references another alias, the resolution is done recursively until a non- aliased sound is found).
*'''random'''
:Default = no list
:This fields allows this sound to have random alternatives when it's played. Include the list of sound mnemonics, separated by commas (curly braces around the list are optional).
*'''skinindex'''
:Default = ''sk_none''
:This field indicates a player skin sound index for this sound. If the player object plays this sound, it will become subject to remapping through the player's skin. The following values are possible for skin index, and each corresponds to one of the fields in the extended Legacy skin format: 
:*sk_none
:*sk_plpain
:*sk_pdiehi
:*sk_oof
:*sk_slop
:*sk_punch
:*sk_radio
:*sk_pldeth
:*sk_plfall
:*sk_plfeet
:*sk_fallht
*'''linkvol'''
:Default = 127 (full volume)
:This field provides a value to be added to the sound's volume when a linked sound is played through this sound definition. Volume range is from 0 to 127, but this field may be any value. The resulting value when added to the base volume will be capped into range. For example, if a sound normally plays at full volume, specifying a negative value in this field will reduce the volume.
*'''linkpitch'''
:Default = 128 (normal)
:This field provides a pitch value to be used when a linked sound is played through this sound definition. Pitch values should be between 0 and 255 when provided.
*'''clipping_dist'''
:Default = 1200
:This value specifies the distance from the origin at which this sound will be completely clipped out; that is, reduced to zero volume and therefore killed completely. The sound engine currently only considers an approximate distance on the X-Y plane, so this behavior may be slightly more rough than expected. The value of this field should be greater than the value of the close_dist field below. If not, the sound will always be played at full volume (this can be intentionally exploited).
*'''close_dist'''
:Default = 200
:This value specifies the distance from the origin at which this sound will be at full volume. Attenuation between the clipping_dist and close_dist values is currently always linear. The sound engine currently only considers an approximate distance on the X-Y plane, so this behavior may be slightly more rough than expected. The value of this field should be less than the value of the clipping_dist field above. If not, the sound will always be played at full volume (this can be intentionally exploited).
*'''pitchvariance'''
:Default = '''none'''
:This field allows specification of the type of pitch variation this sound plays with when pitched sounds are enabled. The following values are allowed: 
:*'''none'''            -- No pitch variation
:*'''Doom'''            -- Pitch variation similar to that used in DOOM v1.1 for most sounds
:*'''DoomSaw'''         -- Pitch variation similar to that used for saw sounds in DOOM v1.1.
:*'''Heretic'''         -- Pitch variation similar to that used in Heretic
:*'''HereticAmbience''' -- Pitch variation similar to that used in Heretic for global ambience.
:In general, DOOM types provide less variation than Heretic types. Note that Eternity has now repaired some bugs in the BOOM sound pitch variation code, and so the effect works much better than it did previously.
*'''subchannel'''
:Default = Auto
:This field allows allocating a sound to a specific subchannel, so that an actor can play several sounds at once, unlike vanilla Doom behavior. Possible values are:
:*Auto - default sound channel
:*Weapon
:*Voice
:*Item
:*Body
:*SoundSlot5
:*SoundSlot6
:*SoundSlot7
*'''pcslump'''
:Default = ""
:Allows associating a PC speaker sound lump with this sound definition. Required if the sound does not use a DS or DP '''prefix''' or if the DP* version of the lump is missing.
*'''nopcsound'''
:Default = false
:If set to true, forces the PC sound to NOT be played even if a valid lump exists for this entry. Default Doom monster pain and active sounds have this flag set to true.
*'''dehackednum'''
:Default = -1
:In order to be accessible to Dehacked patches, a sound definition must be given a unique DeHackEd number. The value zero is reserved and cannot be used. In order to avoid conflict, and to remain compatible with future versions of the Eternity Engine, user sounds should either use DeHackEd numbers between 10000 and 32768, or simply use the value -1 if no thing/frame or DeHackEd access is necessary.

===Example===
 # Define some new sounds
 # This one is only accessible via scripting because it doesn't have a DeHackEd number.
 # (Although a DeHackEd number may be auto-assigned to it if something in EDF attempts
 #  to use its DeHackEd number...)
 
 sound MySound
 {
   lump = foo    # this will play FOO, since prefix defaults to false when
                 # a lump name is explicitly provided. Note that this case is
                 # affected by the change in EDF v1.7. Previously, this would have
                 # played the sound DSFOO, even though the lump name is specified
                 # as "foo". Automatic prefixing now ONLY applies to sounds which
                 # copy their mnemonic to the lumpname and allow prefix to default.
 }
 
 # This entry uses its mnemonic to double as the sound lump name, but already provides
 # the standard DS prefix in the mnemonic.
 
 sound dsblah
 {
   prefix = false  # Because we did not explicitly specify a lump name, the
                   # lump name has become "dsblah", and the default value of
                   # prefix is true. That means we have to change it to false,
                   # or else the game would try to play DSDSBLAH, which is
                   # wrong. This has not changed.
                   
   dehackednum = 10000
 }
 
 # This entry also uses the mnemonic as the sound name, but with prefixing.
 # Since prefix defaults to true when the lump name is not explicitly provided, 
 # the sound lump played will be "DSEXPLOD". This has also not changed.
 
 sound explod
 {
   priority = 128
   dehackednum = 10001
 }
 
 # This entry links to another sound.
 sound BlahLink
 {
   link = dsblah   # we've linked this entry to the dsblah sound
   linkvol = 64    # use some suitable values for these (must experiment)
   linkpitch = 72
   dehackednum = 10002
 }
 
 # This entry overrides a previously defined sound.
 sound explod
 {
   priority = 96        # Maybe we like 96 better than 128...
   dehackednum = 10001  # We can reuse the same DeHackEd number, since it overwrites
 }
 
 # This sound is just an alias for explod. It will play using all the parameters
 # as they are defined in explod. Anything else we defined in this sound would be
 # totally ignored.
 
 sound Explosion { alias = explod }

==Sound sequences==
Sound sequences are effects that play while a sector is moving, a polyobject is moving, or when a Heretic-style (environmental) ambient sound is under way. Similar to things, frames or individual sounds, sequences are defined in EDF by using the '''soundsequence''' block. The mnemonic must be at most 32 characters long. Sound sequence definitions can be cascaded, and the latter ones will overwrite other identically named sequences.

Sector movement sequences are used by placing thing types #1400 to #1500 on the map, inside the designated sectors. The ones numbered from #1400 to #1499 will play the sequence with the '''id''' between 0 and 99, while #1500 will use its first argument in the [[ExtraData]] definition.

In [[UDMF]], sequences can be set directly on sector properties, removing the need for placing things inside.

Polyobject sequences are set up from the [[Polyobject_linedef_types|Polyobj_StartLine and Polyobj_ExplicitLine]] ExtraData linedef specials. '''Polyobj_StartLine''' uses the 3rd argument for this, while '''Polyobj_ExplicitLine''' uses the 4th.

Environmental sequences are set up similarly with sector sequences, by placing thing types #1200 to #1300 anywhere inside the map. #1200 to #1299 use the last two digits to designate the number, while #1300 uses the first ExtraData argument.

'''NOTE:''' You can include all '''soundsequence''' blocks inside a '''ESNDSEQ''' lump. It will be loaded automatically at game startup, independent of '''EDFROOT'''.

===Syntax===

 soundsequence <mnemonic>
 {
   id              <number>
   cmds            { <string>, ... }
   commands        <heredoc string>
   type            <sequence type>
   stopsound       <sound mnemonic>
   attenuation     <attenuation type>
   randomplayvol   <boolean>
   volume          <number>
   minvolume       <number>
   nostopcutoff    <boolean>
   doorsequence    <sound sequence mnemonic>
   platsequence    <sound sequence mnemonic>
   floorsequence   <sound sequence mnemonic>
   ceilingsequence <sound sequence mnemonic>
 }

===Parameters===
The fields are as follows:

*'''id'''
:''Default:'' -1
:Sets up the sound sequence number to recognize it in maps. Environmental sequences use a different namespace from sector ones, and sector sequences can be separated in door, platform and general sequences (see below)

*'''cmds'''
:''Default:'' { "end" }
:'''(Deprecated)''' The list of Hexen-style commands to control the playing of sounds. Each command is written as a string, separated with a comma from the others. While this syntax will continue to be supported, it is recommended that new modifications use the heredoc-enabled syntax via the '''commands''' field instead.

*'''commands'''
:''Default'': @" end "@
:The commands field allows specification of sound sequences in the natural Hexen-derived syntax, without quotations or commas, by embedding the commands one per line inside an EDF heredoc (a literally interpreted string delimited by @" and "@ sequences). This is the recommended method of specification. '''SVN r1420+'''

*'''type'''
:''Default:'' "sector"
:There are four separate namespaces: sector, door, plat and environment. The second is restricted to doors and polys; the third to general moving floors/ceilings and lifts.

*'''stopsound'''
:''Default:'' "none"
:The sound mnemonic to play when the sector stops. Will never happen if this is an environmental sequence.

*'''attenuation'''
:''Default:'' "normal"
:Can be: normal, idle, static, none.

*'''randomplayvol'''
:''Default:'' false
:If set to true, every normal "play" command which doesn't specify a volume will begin at a randomized volume level which may be modified by the user's s_enviro_volume setting. This property exists to support Heretic-compatible global environmental sequence behavior. '''SVN r1420+'''

*'''volume'''
:''Default'': 127

*'''minvolume'''
:''Default:'' -1

*'''nostopcutoff'''
:''Default'': false

===Sequence commands===
*play <sound>
: The indicated sound will be played but the sequence will not delay in moving to the next command. If this is the last sound in the sequence, the sound might be cutoff unless other properties prevent this.
*playuntildone <sound>
: The indicated sound will be played, and the sequence will not move on to the next command or terminate until the sound has finished playing.
*playtime <sound> <time>
: The indicated sound will be played and the sequence will pause for the number of gametics (35 per second) before moving on to the next command.
*playrepeat <sound> 
: The indicated sound will be played continuously without interruption. This command never ends, so the sequence will not terminate unless something such as a sector action stops it externally. This command should not be used in global environmental sequences.
*playloop <sound> <time>
: The indicated sound will be played in a loop every "time" gametics. As above, this command will never end.
*playabsvol <sound> <vol>
: Like the play command, but allows specification of the sound's base volume from 0 to 127.
*playrelvol <sound> <vol>
: Like the play command, but specifies a volume which is relative to the sound sequence's previous volume setting.
*delay <tics>
: Stop the sound sequence from progressing for the indicated number of gametics.
*delayrand <min> <max>
: Delay the sound sequence from progressing for a random number of gametics between and including "min" and "max".
*volume <vol>
: Set the sequence's current absolute volume level to the indicated value between 0 and 127.
*relvolume <vol>
: Modify the sequence's current absolute volume level by the indicated amount. The number specified should be negative to make the sequence more quiet.
*attenuation <attn>
: Set the sequence's attenuation value. This command is executed at game startup and therefore the last one specified is the only one that will take effect.
*stopsound <snd>
: Set the sequence's stopsound attribute. This command is executed at game startup and therefore the last one specified is the only one that will take effect.
*nostopcutoff
: Set the sequence's nostopcutoff attribute. This command is executed at game startup and therefore the last one specified is the only one that will take effect.
*restart
: Restart the current sound sequence. This command should not be used in global environmental sequences.
*end
: End the sequence. This command is not required by the Eternity Engine, and exists for Hexen compatibility.

===Example===
 // This is a sequence playable by name only. It is one of the default sector sequences
 // defined in sounds.edf, and is used by Heretic doors when they close.
 soundsequence EEDoorCloseNormal
 {
   cmds =
   {
      "play EE_DoorOpen",
      "stopsound EE_DoorClose"
   }
 }
 
 // This is an environmental sequence for Heretic, which is used by placing a thing of
 // type 1200 anywhere on the map. It is started by the environmental sequence manager
 // at random, with the probability of it being played being determined by the proportion
 // of 1200 objects to other environmental sequence spots on the map.
 soundsequence EEHticAmbScream
 {
   type = environment
   id = 0
   cmds = { "playuntildone ht_amb1" }
   
   volume = 96
   minvolume = 32
   attenuation = none
 }
 
 // This is a sound sequence meant to be played by a PolyObject. It could also use
 // type sector and would still work, but using type door is more explicit. PolyObjects
 // always use door-type actions when starting sequences, so they check the door lookup
 // first for id numbers between 0 and 63.
 soundsequence PolyDoor
 {
   type = door
   id   = 0
   cmds =
   {
      "play EE_BDoorOpen",
      "stopsound EE_PlatStop"
   }
 }
 
 // This is one of the more complicated environmental sequences from sounds.edf.
 // It plays two alternating footstep sounds every 15 gametics at a constantly
 // decreasing volume level.
 soundsequence EEHticSlowFootSteps
 {
   type = environment
   id = 3
   cmds =
   {
      "playtime ht_amb4 15",
      "playrelvol ht_amb11 -3",
      "delay 15",
      "playrelvol ht_amb4  -3",
      "delay 15",
      "playrelvol ht_amb11 -3",
      "delay 15",
      "playrelvol ht_amb4  -3",
      "delay 15",
      "playrelvol ht_amb11 -3",
      "delay 15",
      "playrelvol ht_amb4  -3",
      "delay 15",
      "playrelvol ht_amb11 -3",
      "nostopcutoff"
   }
   
   volume = 96
   minvolume = 32
   attenuation = none
 }
 
 // Yes, sound sequences can be completely silent :) All fields are defaulting, and
 // the only command in the command list is "end".
 soundsequence EEPlatSilent
 {
 }

==Ambience==
'''Ambience''' sections allow the user to define the behavior of ambient sound spots, which can be placed on maps using DoomEd numbers 14001 through 14065. The first 64 of these objects automatically use the ambience sections with numeric indexes 1 through 64. Object 14065 accepts the index number in its first argument field, which may be specified either through the use of ExtraData via the Hexen map format or via the upcoming UDMF format.

===Syntax===
 ambience
 {
   sound       = <sound mnemonic>
   index       = <number>
   volume      = <number>
   attenuation = <attenuation type>
   type        = <ambience behavior type>
   period      = <number>
   minperiod   = <number>
   maxperiod   = <number>
 }

===Usage===
*'''sound'''
:Default = "none"
:This field specifies the sound to be played by an ambience object using this definition. If the value provided to this field is invalid, no sound will be played. 
*'''index'''
:Default = 0
:Defines the index of this ambience definition. This may be an integer of any value zero or greater, although only the first 256 ambience definitions are usable via the Hexen map format. When an ambience definition has the same index as a previously defined ambience definition, it will overwrite that previous definition. Note that if a thing placed on a map references an invalid ambience sequence, that object will do nothing. 
*'''volume'''
:Default = 127
:The relative volume of this ambient sound, ranging from 0 to 127. This is multiplied by the user's volume setting so that the true range of volume is from 0 to the user's setting. For all attenuation types except "none", the volume is additionally decreased by the user's distance from the ambience object. 
*'''attenuation'''
:Default = "normal"
:This field defines the attenuation behavior of the ambience object. Attenuation is how the sound changes with distance between the listener and the ambience object. The following values are available for this field: 
:*normal -- Use the close_dist and clipping_dist fields defined in the sound definition.
:*idle   -- Use DOOM's normal default sound attenuation behavior.
:*static -- Fades quickly (inaudible from 512 units).
:*none   -- Plays at this ambience definition's volume level regardless of distance.
    
*'''type'''
:Default = "continuous"
:This field defines the repetition behavior of this ambience definition. The following values are available for this field: 
:*continuous -- loops the sound seamlessly
:*periodic   -- restarts the sound every "period" number of gametics
:*random     -- restarts the sound after a randomized wait period determined by the minperiod and maxperiod fields
    
*'''period'''
:Default = 35
:For periodic ambience definitions, this field defines how frequently the sound is restarted in gametics (1/35 of a second). 
*'''minperiod'''
:Default = 35
:For random ambience definitions, this field defines the shortest wait period before the sound will be restarted. 
*'''maxperiod'''
:Default = 35
:For random ambience definitions, this field defines the longest wait period before the sound will be restarted. The ambience object will wait a period of time somewhere between minperiod and maxperiod gametics, inclusive. For proper behavior, maxperiod should be a number greater than minperiod.
===Example===
 ambience
 {
   index       = 0
   sound       = ht_waterfl
   type        = continuous
   volume      = 127
   attenuation = static
 }
 
 ambience
 {
   index       = 1
   sound       = ht_bstsit
   type        = periodic
   volume      = 64
   attenuation = none
   period      = 70
 }
 
 ambience
 {
   index       = 2
   sound       = ht_bstatk
   type        = random
   volume      = 127
   attenuation = idle
   minperiod   = 35
   maxperiod   = 105
 }

==Environmental Sequence Manager==
EDF can alter basic properties of the environmental ambience sound sequence manager. This system runs in every level and randomly chooses environmental sequences to play based on what objects with DoomEd numbers 1200 through 1300 are present on the level (these objects are collected in much the same way as Boss Brain spots or D'Sparil's teleport landings). The probability of a given sequence playing on any particular event is determined solely by how many objects on the level specify that sequence as compared to the total number of objects. 

There can be any number of enviromanager blocks specified, but only the values in the last one parsed will be used. 

===Syntax===
 enviromanager
 {
   minstartwait = <number> // minimum wait time at level start in tics
   maxstartwait = <number> // maximum wait time at level start in tics
   minwait      = <number> // minimum wait time between sequences in tics
   maxwait      = <number> // maximum wait time between sequences in tics
 }
In all cases, the minimum wait times should be less than the maximum. The engine will adjust the values to make this true if it is not.

==Sound environments==
Use of sound environments allows addition of reverberation effects to areas within levels called "sound zones." Sound zones are sets of contiguous sectors which connect to each other by two-sided lines which are not marked with a new ExtraData linedef flag, ZONEBOUNDARY.

To assign a specific sound environment to a zone, use ExtraData to create an EESoundEnvironment object in one of the sectors inside that zone with its first two map arguments set to the two ID numbers of the EDF reverb definition you want to apply while a player is inside that area.

 // Defines a reverb sound environment. ID1 and ID2 are required and must be
 // numbers between 0 and 255. 
 reverb <name> : <id1>, <id2>
 {
  // Roomsize defines the decay time and "volume" of reverberation; the larger
  // the value, the bigger the space.
  // Range 0.0 to 1.07143; default 0.5
  roomsize <float> 
  
  // Damping defines the amount of high-frequency rolloff in the reverb filters.
  // A higher value is analogous to a space filled with fewer reflective objects.
  // Range 0.0 to 1.0; default 0.5
  damping  <float> 
  
  // Wet scale defines the amount of reverberated signal in the reverb output.
  // Range 0.0 to 1.0; default 0.333...
  wetscale <float>
  
  // Dry scale defines the amount of dry (input) signal in the reverb output.
  // Range 0.0 to 1.0; default 0.0
  dryscale <float>
  
  // Width defines the amount of stereo phasing/cross-over in the reverberation.
  // Range 0.0 to 1.0; default 1.0
  width <float>
  
  // Predelay defines the amount of time between sound emission and the first
  // reverb response. Defined in milliseconds; Range 0 to 250; default 0.
  predelay <int>
  
  // The equalized flag, if specified as +equalized, will turn on a three-band
  // equalization pass after the reverb filters. This allows tweaking the amount
  // of low- and high-frequency sound for adjusting the "luminosity" of the
  // effect. Default is -equalized.
  [+-]equalized
  
  // These parameters apply when +equalized is specified:
  
  eq.lowfreq  <float> // Low band upper edge in Hz;  20-20000; default = 250.0
  eq.highfreq <float> // High band lower edge in Hz; 20-20000; default = 4000.0
  eq.lowgain  <float> // Volume factor for low freqs; 0.0-1.0; default 1.0
  eq.midgain  <float> // Volume factor for mid freqs; 0.0-1.0; default 1.0
  eq.highgain <float> // Volume factor for hi  freqs; 0.0-1.0; default 1.0
 }
Adjustments have also been made to EDF ambience and soundsequence definitions which allow either to exclude themselves from application of sound zones. To exclude either type of definition from environmental effects, use the -reverb flag as such:
 ambience <name> 
 {
  ...
  -reverb
 }
 
 soundsequence <name>
 {
  ...
  -reverb
 }
By default, environments apply to all ambience and soundsequence definitions.

[[category:EDF]]