SNDINFO

From ZDoom Wiki
Jump to navigation Jump to search
DoomWiki.org
For more information on this article, visit the SNDINFO page on the Doom Wiki.

SNDINFO contains many sound-related definitions. It allows any sound referred to by its lump name (DSSAWHIT, DSBAREXP, etc.) to be associated with any game event sound such as player pain, death, and revealing of secrets. The names by which the predefined sounds are referred to in SNDINFO are fairly self-explanatory, so we will not cover them now.

SNDINFO lumps are cumulative. All SNDINFO lumps found are read in WAD directory order. This means that you do not have to — in fact you must not — copy all information from the original SNDINFO lump if you want to change something.

Sound assignment

A sound definition is written in one of two syntaxes.

Old syntax:

logicalname lumpname

New syntax:

logicalname = lumpname

The difference between the two is the requirement of the assignment operator (=) by the new syntax. Just write the two names on one line in the file, the logical name (that is, the name that it uses in the other commands here, in the game or in other lumps that use sound name) first and the lumpname of the sound that is to be used second.

Warning: The two syntaxes can NOT to be mixed within the same file; if the first sound definition in the file uses the old syntax, for example, then all other sound definitions in that file must also use the old syntax, or they won't be recognized.

The new syntax is preferred to use over the old one as it is more robust, since it avoids the problems with the old one not being able to detect badly formatted names.

If you want to use file names which are longer than 8 characters, then the specified file has to be enclosed in quotes ("") and the full path has to be given:

logicalname "sounds/<some subfolders>/<filename>.<file extension>"

Commands

SNDINFO supports the following commands:

(Note: for many commands, using * as the sound name will mean that the command will apply to all sounds that do not specify otherwise.)

  • $alias aliasname soundname
Assigns a second logical name to an already existing sound. The existing sound can also be a random sound or another alias. Any change to the original sound in subsequent SNDINFO lumps is automatically transferred to the new sound.
  • $ambient <index> <logicalsound> [type] <mode> <volume>
Defines an ambient sound which is played when an ambient sound thing (14065) is placed in a map. <index> specifies which thing or which parameter for the generic ambient sound thing has to be used. <logicalsound> specifies the sound to be played, <volume> the volume at which it is played.
type can be one of the following:
  • point <atten>
Defines a positional sound. The volume at which the sound is played decreases with distance. The optional parameter <atten> specifies how quickly this decrease occurs, with larger values meaning a faster falloff in volume. This is specified as a floating point value. The default for <atten> is 1.0.
  • surround
Plays the sound at full volume in surround mode.
  • world
Plays the sound at full volume regardless of distance. The keyword “world” is optional.
mode can be one of the following:
  • continuous
Plays the sound as a repeating endless loop.
  • random <minsecs> <maxsecs>
Plays the sound at random intervals. The minimum and maximum length of this interval can be specified in seconds. Both values are floating point numbers.
  • periodic <secs>
Plays the sound at regular intervals. The length of these intervals is specified in seconds as a floating point value.
  • $archivepath string
Ignored. In Hexen, this works in concert with a -devsnd command line parameter, to indicate from where to load sound files instead of the sound lumps in the archive. ZDoom, having the ability to load directories as archives and loose files as lumps, does not need this Hexen feature; which was ignored in normal conditions anyway.
  • $attenuation aliasname value
Defines a multiplication factor for sound attenuation. Giving a value of zero will result in a sound that is always played with no attenuation, that is to say at full volume.
Attenuation is done by multiplying the sound's distance by the attenuation value and using that as the distance in volume calculations.
For example:
  • If attenuation is 2, then the sound will fade out with distance 2x faster. In other words, you can only hear it 2x closer.
  • If attenuation is 0.5, then the sound will fade out with distance half as fast; you can hear it 2x further.
  • $edfoverride
This command is defined for Eternity Engine compatibility but completely ignored. (In EE, it means that the SNDINFO lump takes precedence over what is defined in Eternity's DoomWikiLogoIcon.pngnative definition files.)
  • $ifdoom
  • $ifheretic
  • $ifhexen
  • $ifstrife
Reads the following definitions up to the next $endif only if the specified game is played.
  • $limit soundname <amount> [limitdistance]
Specifies that at most <amount> instances can be played at once. A value of 0 means no limit at all. Defaults to 2.
limitdistance specifies how far the limit takes effect. It defaults to 256, as in, two sounds further than 256 units apart can be played even if $limit would cause them to be evicted otherwise.
  • $map mapnumber musicname
This was the way level music was defined in Hexen. It is merely provided for compatibility and should not be used anymore. Level music should be defined in the MAPINFO lump with the rest of the level's parameters.
  • $mididevice musicname device [parameter]
Sets the default device to use to play a given song file, which can be useful if the song only sounds good using one of the playback methods. Valid device names include default (does not change the user's choice), standard (uses the Windows API), timidity, opl, gus, fluidsynth, and finally wildmidi.
An optional parameter can be passed. The options available depend on the device and work as override to a console variable, so the parameter should have the same form as the console variable it replaces.
  • $musicalias musicname remappedname
Allows remapping of music tracks. Can be used, for example, with high quality replacement soundtrack to avoid duplicate tracks and reducing its size. Mapping a track to 'none' means that starting the remapped song will have no effect at all. There's one limitation though: If you load a WAD with the same music name after the one with the SNDINFO lump the mapping will be ignored. This is so that music resources can use this command without interfering with WADs that replace the music with their own.
  • $musicvolume musicname factor
Sets a volume scaling factor for music tracks. This is used to compensate for music that has audibly different volume.
  • $pitchset soundname <float-value> [range]
Specifies the direct pitch of a sound to play at. Overrides $pitchshift, but is overridden by A_StartSound's pitch parameter.
Unlike $pitchshift, the value is a floating point value. Standard pitch is 1.0. Lower values will make the sound play slower, and vice versa.
If a second value is set to something other than 0.0, the engine will treat it as a random range between the two.
Default is 0.0. Values at 0.0 or lower means the engine will not set a direct pitch and resort to using $pitchshift if applicable.
Note: If setting a specific sound that will be used inside of a '$random', this must be defined before the $random definition in order to take effect.
  • $pitchshift soundname <range>
Specifies how much the pitch of the specified sound may be randomly altered when it is played. <range> may be in the range of 0 to 7.
  • $pitchshiftrange <range>
Sets a default pitch shift value that is applied to all subsequent sound definitions.
  • $playeralias playerclass gender logicalname otherlogicalsound
Creates an alias to the existing logical sound.
  • $playercompat playerclass gender logicalname compatibilityname
Defines a compatibility alias for a specific player sound. If any sounds with these compatibility names are defined later, they will redefine the corresponding player sounds instead. Likewise, if they are played, they will play the corresponding player sound instead.
  • $playersound playerclass gender logicalname lumpname
Defines a sound used by a player. <playerclass> must be 'player' if the sound is used for a stock Doom, Strife, or Heretic class. If it is for a custom class, it can be named anything, so long as Player.SoundClass uses the same name. In Hexen, it can be either “fighter”, “mage” or “cleric”, in addition to any custom classes for the game. Gender can be “male”, “female” or “other”. Here you can find a list of all known player sounds and their meaning. If you wish to use additional sounds for custom skins, you use this like custom classes by defining the sounds that you wish to use, but instead you put the skin name into the <playerclass> string.
Note: An interesting note: ZDoom supports different player pain sounds depending on health. In Doom, Heretic and Hexen there is only one player pain sound, so it is handled like this in SNDINFO:
$playersound           player	male	*pain100	dsplpain
$playersounddup        player	male	*pain75		*pain100
$playersounddup        player	male	*pain50		*pain100
$playersounddup        player	male	*pain25		*pain100

The *pain100 used instead of a lump name for pain75, pain50, and pain25 tells those sounds to refer to pain100 for a sound lump to play. If you want you can change this, though, so you really have different pain sounds.


Another feature of the player sounds is that you can specify a custom damage type for pain and death sounds. You do this by defining the sound as follows:

$playersound           player  male    *death-fire     dsburn

When the player takes damage, ZDoom will attempt to find a sound with the matching damagetype first, and then will fall back to the generic sound (e.g. *death) if it is not found.


Finally, if a player sound is explicitly set to dsempty, no sound will be played. Setting it to another empty or invalid sound will make the engine look for a valid sound to play in the default or a parent player class.

  • $playersounddup playerclass gender logicalname otherplayersound
Creates an alias to the existing player sound.
  • $random aliasname { logicalname1 logicalname2 logicalname3 ... }
Defines a random sound. The newly defined alias can be used like a regular sound but any time it is used one of the sounds specified in the list is randomly selected. The number of sounds in the list is unlimited. Note that for this to work, the logicalnames within the brackets must be assigned to real lumpnames on separate lines. (See example below.)
  • $registered
This command is defined for Hexen compatibility but completely ignored.
  • $rolloff soundname <mindist> <maxdist>
  • $rolloff soundname <type>
Sets the attenuation for the sound. <mindist> (default 200) is the distance from the center of the sound trigger at which the sound is played at full volume, after which the sound drops off in volume until it hits <maxdist> (default 1200) is the distance at which the sound becomes inaudible. This allows different sound curves to be defined on a per-item basis.
If a type is specified, then ZDoom uses one of the predefined methods to compute rolloff. Available types are:
  • custom — Uses a lookup table.
  • linear <min distance> <max distance> — Uses a linear method to adjust the sound volume to the distance.
  • log <min distance> <rolloff factor> — Uses a logarithmic method to adjust the sound volume to the distance; anything closer than min distance is full volume and beyond that it has a scalar that controls how quickly the volume drops off.
  • $singular soundname
Specifies that this sound can only be played once at a time over the entire map. This differs from using $limit 1 in that $limit will prevent other sounds from being played if they would be heard; $singular will prevent the sound from playing if it is already playing somewhere in the map, even if it is too far to be heard.
  • $volume soundname <volume>
Specifies a modifier to apply to this sound's volume whenever it is played. This value is multiplied by the volume specified in the script or actor definition triggering the sound to determine the final volume. The default and maximum value is 1.0. It is not possible to amplify a sound's volume with this instruction, only decrease it.

Examples

This adds a new custom sound with a logical name "mymonster/death" pointing to a file called MMONDIE (which can be in any format):

mymonster/death MMONDIE

This picks one of the three sounds randomly to play for "mymonster/death":

$random mymonster/death { mymonster/death1 mymonster/death2 mymonster/death3 }
mymonster/death1 MMONDIE1
mymonster/death2 MMONDIE2
mymonster/death3 MMONDIE3

This is an example of adding a sound file with a long file name:

mymonster/death "sounds/monsters/MyMonster/mymonster_death.ogg"

This example randomizes the player's death sound to one of three different sounds:

$random pl_death { player/death1 player/death2 player/death3 }

player/death1 pldth1
player/death2 pldth2
player/death3 pldth3

$playeralias           player  male    *death          pl_death

// example for long file names
shield/confirm		"sounds/player/ShieldConfirm.ogg"

Note that the actual sounds that will be played when a player dies are pldth1, pldth2 and pldth3.

Multiple SNDINFO Lumps

The #include directive cannot be used with SNDINFO, but WADs may include multiple SNDINFO lumps. In PK3 format, multiple SNDINFO lumps can be used by giving them unique extension names. For example, SNDINFO.weapons, SNDINFO.monsters, SNDINFO.ambient, et cetera.

See also