Merge branch 'the-sound-of-music-documentation' into 'master'

User documentation on how music and sound effects work in OpenMW.

See merge request OpenMW/openmw!2518

docs/source/reference/modding/index.rst

@@ -25,6 +25,8 @@ about creating new content for OpenMW, please refer to
 	texture-modding/index
 	custom-models/index
 	font
+	sound-effects
+	music
 	sky-system
 	custom-shader-effects
 	extended

docs/source/reference/modding/music.rst

@@ -0,0 +1,26 @@
+#####
+Music
+#####
+
+
+The music system in OpenMW is hard-coded and audio files are used automatically 
+when placed into correct folders.
+
+* ``data/music/explore`` - Folder contents are played outside combat, shuffling between available files.
+* ``data/music/battle`` - Folder contents are played during combat, shuffling between available files.
+
+Three special files also require a specific name. In this example a ``.mp3`` 
+format is used, but any other format will also work as long as the filename is 
+correct.
+
+* ``data/music/special/morrowind title.mp3`` - Main menu music.
+* ``data/music/special/mw_death.mp3`` - Plays when the player dies.
+* ``data/music/special/mw_triumph.mp3`` - Plays when the level up menu appears.
+
+
+Supported Formats
+*****************
+
+OpenMW uses `FFmpeg framework <https://ffmpeg.org/>`_ and thus supports a great 
+variety of formats. Using either ``.mp3`` or ``.ogg`` for music files is a 
+common choice.

docs/source/reference/modding/sound-effects.rst

@@ -0,0 +1,373 @@
+#############
+Sound Effects
+#############
+
+Every game needs sound effects to create the best possible player experience.
+Audio files are played during a variety of in-game situations and this is how
+they are set up in OpenMW. Some are user-definable, while a lot of them are
+hard-coded to specific names.
+
+
+Supported Formats
+*****************
+
+OpenMW uses `FFmpeg <https://ffmpeg.org/>`_ and thus supports many formats. 
+For sound effects we suggest using 16-bit ``.wav`` files.
+
+
+Sound File, Sound, Sound Gen
+****************************
+
+* `Sound File` record in OpenMW-CS is the audio file on the disk. When files are placed in ``data/sounds`` and its subfolders, OpenMW-CS will list them in a table. `Sound File` records aren't used directly in OpenMW-CS but must first be assigned to a `Sound` record. 
+* `Sound` is the record that can be assigned to other records in OpenMW-CS. It needs a `Sound File` assigned, has volume, min range, and max range properties.
+* `Sound Generator` record is used for creature animation events (groan, get hit, die, footsteps). It takes the `Sound` record and defines what creature uses this effect and when.
+
+.. note:: Newly created `Sound` records in OpenMW-CS have their `Max Range` value set to 255.
+    This can cause the sound to not be audible in-game. To fix this, set the mentioned value to 0.
+
+
+Hardcoded Effects
+*****************
+
+The following sound effects are hard-coded. They require a properly named `Sound` record and will then be used in their relevant in-game situations. 
+
+Ambient
+=======
+
+.. list-table:: 
+   :widths: 35 65
+   :header-rows: 1
+
+   * - Sound name
+     - Situation used
+   * - ``ashstorm``
+     - During an ash storm
+   * - ``blight``
+     - During the red blight storm
+   * - ``blizzard``
+     - During a blizzard
+   * - ``rain``
+     - During rainy weather
+   * - ``rain heavy``
+     - During stormy weather
+   * - ``thunder0``
+     - Played randomly during stormy weather
+   * - ``thunder1``
+     - Played randomly during stormy weather
+   * - ``thunder2``
+     - Played randomly during stormy weather
+   * - ``thunder3``
+     - Played randomly during stormy weather
+   * - ``underwater``
+     - When the camera is under the water level
+   * - ``water layer``
+     - When the player is near the water level
+
+.. note:: Names for these sounds can be changed in ``openmw.cfg`` but we strongly suggest they stay the same.
+    Another issue is with ``ashstorm``, ``blight``, ``blizzard`` which have missing or erroneous fallback lines,
+    unless they were imported from Morrowind.
+    These will be fixed with the planned dehardcoding of weather types and using Lua.
+
+
+Equiping items and weapons
+==========================
+
+Sound names in this category follow a pattern.
+
+* Each name contains the type of object this sound applies to.
+* Names ending with ``up`` are used when the item type is picked up, equiped, readied, or grabbed in the inventory.
+* Names ending with ``down`` are used when the item type is dropped, unequiped, put away, or released in the inventory.
+
+.. list-table:: 
+   :widths: 35
+   :header-rows: 1
+
+   * - Sound name
+   * - ``item ammo up``
+   * - ``item ammo down``
+   * - ``item apparatus up`` 
+   * - ``item apparatus down``
+   * - ``item armor heavy up``
+   * - ``item armor heavy down``
+   * - ``item armor light up``
+   * - ``item armor light down``
+   * - ``item armor medium up``
+   * - ``item armor medium down``
+   * - ``item bodypart up``
+   * - ``item bodypart down``
+   * - ``item book up``
+   * - ``item book down``
+   * - ``item clothes up``
+   * - ``item clothes down``
+   * - ``item gold up``
+   * - ``item gold down``
+   * - ``item ingredient up``
+   * - ``item ingredient down``
+   * - ``item lockpick up``
+   * - ``item lockpick down``
+   * - ``item misc up``
+   * - ``item misc down``
+   * - ``item potion up``
+   * - ``item potion down``
+   * - ``item probe up``
+   * - ``item probe down``
+   * - ``item repair up``
+   * - ``item repair down``
+   * - ``item ring up``
+   * - ``item ring down``
+   * - ``item weapon blunt up``
+   * - ``item weapon blunt down``
+   * - ``item weapon bow up``
+   * - ``item weapon bow down``
+   * - ``item weapon crossbow up``
+   * - ``item weapon crossbow down``
+   * - ``item weapon longblade up``
+   * - ``item weapon longblade down``
+   * - ``item weapon shortblade up``
+   * - ``item weapon shortblade down``
+   * - ``item weapon spear up``
+   * - ``item weapon spear down``
+
+
+Combat
+======
+
+.. list-table:: 
+   :widths: 35 65
+   :header-rows: 1
+
+   * - Sound name
+     - Situation used
+   * - ``bowpull``
+     - Start of a bow attack 
+   * - ``bowshoot``
+     - A bow is released and fires an arrow
+   * - ``critical damage``
+     - Critial damage is dealt
+   * - ``crossbowpull``
+     - Start of a crossbow attack
+   * - ``crossbowshoot``
+     - A crossbow is released and fires a bolt
+   * - ``heavy armor hit``
+     - A character wearing heavy armour is hit   
+   * - ``light armor hit``
+     - A character wearing light armor is hit
+   * - ``medium armor hit``
+     - A character wearing medium armor is hit
+   * - ``miss``
+     - An attack misses
+   * - ``weapon swish``
+     - Melee weapon attack. The sound is modulated based on attack strength.
+   * - ``hand to hand hit``
+     - Hitting a valid target with fists
+   * - ``hand to hand hit 2``
+     - Hitting a valid target with fists
+
+
+UI
+==
+
+.. list-table:: 
+   :widths: 35 65
+   :header-rows: 1
+
+   * - Sound name
+     - Situation used
+   * - ``book close``
+     - A book or journal is closed
+   * - ``book open``
+     - A book or journal is opened
+   * - ``book page``
+     - Go to the previous page of a book or journal
+   * - ``book page2``
+     - Go to the next page of a book or journal
+   * - ``menu click``
+     - Mouse click on a button
+   * - ``scroll``
+     - book object of a scroll type is opened or closed
+
+
+Movement
+========
+
+Movement sounds apply to the player and NPCs, together reffered to as characters.
+Each sound is played in a specific in-game situation and most require a corresponding textkey.
+
+* When the sound name ends in ``left`` it plays when ``soundgen: left`` occurs.
+* When the sound name ends in ``right`` it plays when ``soundgen: right`` occurs.
+* Landing requires ``soundgen: land``
+
+.. list-table:: 
+   :widths: 25 75
+   :header-rows: 1
+
+   * - Sound name
+     - Situation used
+   * - ``defaultland``
+     - When a character lands on the ground
+   * - ``defaultlandwater``
+     - When a character lands in water
+   * - ``swim left``
+     - When swimming
+   * - ``swim right``
+     - When swimming
+   * - ``footbareleft``
+     - While walking, running, or sneaking on land and not wearing armour
+   * - ``footbareright``
+     - While walking, running, or sneaking on land and not wearing armour
+   * - ``footheavyleft``
+     - While walking, running, or sneaking on land and wearing heavy armour boots
+   * - ``footheavyright``
+     - While walking, running, or sneaking on land and wearing heavy armour boots
+   * - ``footlightleft``
+     - While walking, running, or sneaking on land and wearing light armour boots
+   * - ``footlightright``
+     - While walking, running, or sneaking on land and wearing light armour boots
+   * - ``footmedleft``
+     - While walking, running, or sneaking on land and wearing medium armour boots
+   * - ``footmedright``
+     - While walking, running, or sneaking on land and wearing medium armour boots
+   * - ``footwaterleft``
+     - While walking, running, or sneaking in shallow water
+   * - ``footwaterright``
+     - While walking, running, or sneaking in shallow water
+
+
+Interactions
+============
+
+.. list-table:: 
+   :widths: 35 65
+   :header-rows: 1
+
+   * - Sound name
+     - Situation used
+   * - ``disarm trap``
+     - A trap is successfully disarmed
+   * - ``disarm trap fail``
+     - Attempt to disarm a trap is unsuccessful
+   * - ``enchant fail``
+     - Enchanting or recharging an item fails
+   * - ``enchant success``
+     - Enchanting or recharging an item is successful
+   * - ``lockedchest``
+     - Trying to open a locked chest
+   * - ``lockeddoor``
+     - Trying to open locked doors
+   * - ``open lock``
+     - Unlock attempt succeeds
+   * - ``open lock fail``
+     - Unlock attempt fails 
+   * - ``potion fail``
+     - Brewing a potion fails
+   * - ``potion success``
+     - Brewing a potion succeeds
+   * - ``repair``
+     - Repair of an item is successful
+   * - ``repair fail``
+     - Repair attempt of an item fails
+   * - ``spellmake fail``
+     - Creating a new spell is successful
+   * - ``spellmake success``
+     - Attempt at creating a new spell fails
+   * - ``drink``
+     - The player consumes a potion
+   * - ``swallow``
+     - The player consumes an ingredient
+
+     
+Misc
+====
+
+.. list-table:: 
+   :widths: 35 65
+   :header-rows: 1
+
+   * - `Sound` name
+     - Situation used    
+   * - ``torch out``
+     - When the currently equipped torch is extinguished
+   * - ``skillraise``
+     - When a skill is raised.
+   * - ``drown``
+     - Looping while the player is underwater and out of breath 
+   * - ``health damage``
+     - When a character or creature takes damage
+
+
+User-defined Sound Effects
+**************************
+
+Lights
+======
+
+Objects of `Light` type can be assigned a sound record that will be played repeatedly.
+
+
+Activators
+==========
+
+`Activators` can play a sound effect through their assigned script. This method  
+can be used to place unique, localized sound effects in the world.
+
+
+Doors
+=====
+
+Objects of `Door` type can be assigned two sounds. One is played when the door
+is used or opened. The other is played when the door is closed. Locked door
+sound is hardcoded and listed in a prior table.
+
+
+Magic effects
+=============
+
+Each `Magic Effect` has four slots where sounds are assigned.
+
+* `Casting Sound` - when the spell with this magic effect is cast
+* `Hit Sound` - when the spell hits a target
+* `Area Sound` - when the spell hits an area target
+* `Bolt Sound` - projectile from this magic effect
+
+
+Regions
+=======
+
+A `Region` has a `Sounds` table where it can be assigned any number of sounds. 
+These are played while the player is in this region and are given a chance how 
+often they will be heard.
+
+
+NPCs speaking
+=============
+
+NPCs can utter a `Sound` in specific in-game situations. These are assigned through `Topic Infos` and occur
+depending on the `Topic` in use.
+
+
+* Alarm
+* Attack
+* Flee
+* Hello
+* Hit
+* Idle
+* Intruder
+* Thief
+
+
+Creatures
+=========
+
+`Creatures` get sound effects through `Sound Generator` records. A `Sound Generator` is assigned
+a creature it will affect and set a type.
+
+* Land
+* Left Foot
+* Moan
+* Right Foot
+* Roar
+* Scream
+* Swim Left
+* Swim Right
+
+Each type relates to a specific in-game event or an event defined in the creature's animation textkey file.