Guide: Siege University - 210: Sounds

==Introduction==
In this document, we will look at how sound works in Dungeon Siege. Topics covered will include placing sounds with Siege Editor, and understanding Material and Voice sounds. Readers interested solely in placing sounds in maps need only be concerned with the first section dealing with that topic. That section assumes a basic understanding of placing objects using Siege Editor and configuring the template properties of placed objects. 
Readers who continue on to the topics of Material and Voice sounds should be familiar with the issues discussed in Guide: Siege University - 201: Templates. 
Throughout the document below, we will be looking at a file named sounddb.gas. You can find this file in the directory \world\global\sounds\. This document is largely focused on sound and sound related files found in the directory \sound\Effects\. 
An appendix has been included covering the topics of how to make elevator material sounds, Sound Effect Descriptors (SEDs), and sound priority. 
==Placing Sounds with Siege Editor==
===Sound Emitters and Sounddb.gas===
Within a region you may place game objects that will act as sources of sound. These objects, called sound emitters, are gizmos, which can be placed and configured in Siege Edit. Sound emitters play sounds not by referring to a sound filename itself, but by using a name given to a sound sample in the [global_voice] block of the file sounddb.gas (found in \world\global\sounds\). 
An entry in the [global_voice] block of sounddb.gas will contain an "event name" that is used in a sound emitter, and a corresponding sound sample filename of a .WAV file (not including the file extension) in \sound\Effects. 
An example [global_voice] sound entry, taken from sounddb.gas: 
 env_lakeside: * = s_e_env_lakeside;
In the above example, "env_lakeside" is the event name that we will reference in a sound emitter, and "s_e_env_lakeside" is the name of a .WAV found in \sound\Effects. 
Using an existing sound, then, involves configuring a sound emitter to play a sample by referring to the sample's event name. If you wish to add a new sound to use in your map, simply add that sound sample (in .WAV format) to \world\global\sounds\Effects\ and make a new entry in [global_voice] using the format: 
 event_name: * = sample_name;
===Using Sound Emitters===
There are two types of placed sound emitter objects available. These are emt_sound, and emt_sound_act. These two sound emitters can in the gizmos/special folder located in the object browsing window of SE. 
Each of these emitters allows you to specify the sound event you wish to play, and configure how the sound will be played. The difference between these two emitters is that emt_sound_act, unlike the emt_sound, may be turned on and off by sending it a we_req_activate or we_req_deactivate message (refer to SiegeU: 203A - Triggers II for more information on sending messages). The emt_sound sound emitter, however, is "cheaper" to use in terms of game performance. As a general rule, always use emt_sound unless you specifically need to turn an emitter on and off. 
Note that "emt_sound" and "emt_sound_act" are the "fuel block" (a.k.a template) names for these objects. This article assumes that Siege Edit's Content Display is set to this fuel block view (in Siege Editor, the "Preferences" window will allow you to set this Content Display view). 
===Configuring a Sound Emitter===
After placing a sound emitter in your region, open its Template Properties in the Object Properties window. Look for the sound_emitter block (or sound_emitter_act if using an emt_sound_act). This block will allow you to configure how an event sound is played. We will discuss some of the settings available below. 
* repeat: This setting will make the sound continually repeat, based on values that you supply for repeat_rate and max_repeat_rate.
* repeat_rate, max_repeat_rate: The repeat_rate is the amount of time (in seconds) that should pass from the beginning of the event sound and when the sound is restarted. Supplying a max_repeat_rate allows you to make a range of time from which a randomly selected time will be chosen to restart the sound.
* event_sound: The name of the event sound to play, as listed in sounddb.gas' [global_voice] block.
* min_dist, max_dist: The distance from the emitter, in meters, at which the intensity of the sound begins to fall off, and the distance at which the sound intensity reaches zero, respectively. 
There are two alternatives to repeat rates for controlling when a sample is played. Each of these is based of the in-game time of day.
* start_hour, stop_hour: Game hour to begin playing the event sound, and the game hour at which to stop.
* time_chunk: A portion of a game-day during which an event sound should be played.
==Material Sounds==
Material sounds are centered on a material type that is assigned in the template of a game object (via the [aspect] component's "material" field), and the [sounddb] block in the file sounddb.gas (found in \world\global\sounds\). 
A material type is a way of assigning a property to a game object that describes the object for the purposes of game sounds. An actor such as the Ice Warrior, for example, has a material of "ice", and a weapon such as a short sword has a material of "steelsword". When the Ice Warrior or the shortsword are involved in combat, these assigned materials are taken into account when generating combat sounds or other sound-requiring events. 
The material type for a game object is assigned in the [aspect] block of that object's template (or template instance). When a material sound event takes place (such as in melee combat - a sword hitting plate armor, for instance), the game engine looks for entries in the [sounddb] block of the file sounddb.gas for the materials of the objects involved in the event and, if found, a corresponding sound is played. 
===Adding Materials and Material Sounds===
Materials are assigned in the [aspect] block of a game object's template by defining a value in the material field.
Example aspect block assigning a material. 
 [aspect]
 {
 material = ice;
 }
Adding an entry for a material event in sounddb.gas involves adding event information to the [sounddb] block. This [sounddb] entry will contain a source and destination material, an event name, and information about the sound sample to be played. The sound sample information consists of the name of the sound sample (or "SED") to play, and sound priority information for the entry (SEDs and sound priority are discussed in the Appendix below). 
The "source" and "destination" materials can best be thought of in the context of melee combat (although they are taken into account in ranged and even magical combat, as well). We will use for our example a fight between an attacker who is using a sword, and a defender wearing leather armor. When the attacker swings a sword and hits the defender's armor, an "attack_hit_glance" event occurs. 
For this material event the source material would be "steelsword" (as defined in the base_sword template in contentdb\templates\regular\interactive\wpn_sword.gas). The destination material would be "leather" (as defined in the base_body_armor_leather template in amr_body_leather.gas). 
In our example, then, we have a source material of "steelsword" and a destination material of "leather" for the event "attack_hit_glance." Looking in the [sounddb] block of sounddb.gas, we see that for such an event, s_e_hit_steelsword_flesh1_SED would be played. 
It is interesting to note that the material types are arbitrary - you can create any material type you like and specify that material type within an object's template. As long as an entry in the sounddb has been added for that material type for the event that occurs (e.g. attack_hit_glance), the specified sound will play. 
An example [sounddb] entry taken from sounddb.gas: 
 steelsword:leather:attack_hit_glance:*=s_e_hit_steelsword_flesh1_SED;
A [sounddb] entry follows this format: 
 [source_material]
 {
 [destination_material]
 {
 [event]
 {
 * = sound_name;
 priority = low, norm, high, or always;
 ...
 }
 ...
 }
 ...
 }
 ...
or using standard .GAS file "shorthand": 
 source_material:destination_material:event:* = sound_name; 
 source_material:destination_material:event:priority = norm;
Note that the sound_name may be either the filename of a .WAV, or an "SED" (an SED is a .GAS file that resides in the \sound\Effects directory, and contains more information to tell the engine "how" to play the sound). The file extension should not be included in the sounddb entry. Again, sound priority and SED files are discussed in the Appendix at the end of this document. 
===Material Event Rules===
When a material event occurs, a series of rules, or steps, are followed to determine the source and destination materials of the game objects involved in the event. 
Source material is found by a check for material done first on the source object's ammo, then on the contents (if any) of the weapon hand, and finally on the actor template itself. With this in mind, an archer could have a source of "arrow", a spellcaster could have a source of "fireball", a sword-wielding fighter could have a source of "steelsword", and an unarmed krug scout could have a source of "flesh" (fists). 
Destination material is found by a check for material done first on the destination object's shield, followed by a check for material on the torso armor, and finally on the actor's template itself. For example, if a warrior wearing plate armor is holding a wooden buckler, the warrior's destination material is "wood" (the material specification of the shield). However, if that same warrior then dropped the shield, the destination material becomes "steel" (the material specification of the plate armor). 
==Voice Event Sounds==
A "voice event" is a sound event that is specific to a particular object, or objects within the same specialization tree (unless later overridden, of course). Examples of voice event sounds are the sound an actor plays when it dies, or the sound an item plays when the item is dropped on the ground. A voice event may be found in the template of an object in its [aspect] [voice] block, or in the [global_voice] block of sounddb.gas. 
Voice events, placed within the aspect:voice block, follow this format: 
[event]
 {
 * = sound_name;
 * = sound_name2;
 ...	
 priority = low, norm, high, or always;;
 }
An example [voice] block from the base_darkling template in darkling.gas, showing multiple events in shorthand format: 
 [voice]
 {
 [cast] { * = s_e_attack_darkling; }
 [die] { priority = high; * = s_e_die_darkling; }
 [enemy_spotted] { priority = high; * = s_e_call_darkling_SED; }
 [hit_glance] { priority = low; * = s_e_hit_darkling_SED; }
 }
In the above example, the base_darkling template's [voice] block contains multiple events ("cast", "die", etc.), consisting of sound name and priority. Check the documentation in sounddb.gas for a more extensive list of event names. 
When a voice event is requested, the engine tries to play a sound by performing a query. First, the aspect:voice block of the object involved is checked for an [event] (cast, die, enemy_spotted, etc). Next, if the game object's material is not of type 'generic' (if it has a material value specified in the [aspect] block), the [sounddb] in sounddb.gas is checked using the object's material as source and generic as the destination type. And, failing this, the [global_voice] block of sounddb.gas is checked. 
==Appendix A==
===Making New [sounddb] Elevator Material Entries===
Elevator gizmos contain a "material" field, which references [sounddb]. By supplying a destination material name, an elevator will play sounds based on elevator events. See the Siege U 206: Elevators for more information. 
A material that will be used for an elevator should use a source material of "elevator", and a destination material name supplied by you. It is this destination material that should be entered into the "material" field of an elevator gizmo. 
The events that take place during an elevator transition that can be used in a material are level_1, level_2, moving_1, and moving_2. An elevator material would comprise of a sound name for each event used. 
Example elevator material "sd_large" from soundb.gas: 
 elevator:sd_large:moving_1:* = s_e_env_elevator_lrg_start;
 elevator:sd_large:moving_2:* = s_e_env_elevator_lrg_start;
 elevator:sd_large:level_1 :* = s_e_env_elevator_lrg_stop;
 elevator:sd_large:level_2 :* = s_e_env_elevator_lrg_stop;
===Sound Effect Descriptors ("SED"s)===
As you may have noticed, "SED"s can often be used interchangeably with actual .WAV filenames when calling a sample to be played. 
SEDs, or Sound Effect Descriptors, are .GAS files that contain configurable information that affects the playback of a particular sound sample. An SED can control the playback rate of a sample, the maximum number of simultaneous instances of a sample that may be played, and the override falloff distance of a sample. 
SEDS appear in \sound\Effects\, and accompany a particular sound file. Our naming convention has been to use the file name of a sound sample followed by "_SED" to name each SED .GAS file (example: s_e_spell_zap_cast_SED.gas is an SED of s_e_spell_zap_cast.WAV). 
* max_simultaneous_samples: maximum number of instances of this sample that may be played at any one time. 
* min_playback_rate , max_playback_rate: A percentage range of rate between which a random rate will be chosen to play the sample. 
* min_override_dist , max_override_dist: distance, in meters, for sound falloff. This forces this sound to always play with these falloff values, overriding values set in an emitter. 
An SED may contain any or all of the above properties. In sound events where a sound sample is called, an SED for that sample may be called instead. 
Example SED for sound sample s_e_env_brush_rustle: 
 [t:sed,n:s_e_env_brush_rustle_SED]
 {
 sound_effect_file = "s_e_env_brush_rustle";
 max_simultaneous_samples = 2;
 min_playback_rate = 0.9;
 max_playback_rate = 1.1;
 min_override_dist = 12.0;
 max_override_dist = 14.0;
 }
===Sound Priority===
During normal gameplay, a large number of sounds are played on a limited number of sound channels. During these situations when there are more requests to play a sound than there are available sound channels, a sound event's priority is used to decide which sounds play and which are cut. 
Sound priority consists of 4 levels, which are, in ascending order of priority, low, norm, high, and always. These are assigned to a sound event either in a template or in sounddb.gas (though not in effect scripts), with the default priority being "norm". Note that sound event priority may not be set in effect scripts. 
When a sound is requested to play and there are no unused sound channels, a sound with a lower priority than the requested sound will be "bumped" in favor of the new sound. If all samples currently playing are of a higher priority than the requested sample, the requested sample will not be played. 
Sound priority uses the following format: 
	
 [event]
 {
 * = sound_name;
 priority = low, norm, high, or always;
 }
Note that ambient and environmental sounds played via moods, as well as user interface sounds, will always play with the highest priority, independent of any priority that may be given in sounddb.gas or elsewhere.
==Navigation==