Wiki chapters for context-sensitive music (#6197)

* Wiki chapters for context-sensitive music

* Wiki chapters for context-sensitive music - matched to code

docs/wiki/Audiovisual-Mods.md

@@ -41,4 +41,51 @@ This works like graphics, except no atlas is involved. E.g. you include a sounds
 
 
 ## Supply additional music
-Sound files (mp3 or ogg) in a mod /music folder will be recognized and used when the mod is active. Tracks will play randomly from all available tracks (with a little bias to avoid close repetition of tracks). There is no overriding - a "thatched-villagers.mp3" in a mod will play in addition to and with the same likelihood as the file that the base game offers to download for you. There is no hard technical limit on bitrate or length, but large bandwidth requirements may lead to stuttering (The end of a "next turn", right before the world map is updated, and with very large maps, is the most likely to cause this).
+Sound files (mp3 or ogg) in a mod /music folder will be recognized and used when the mod is active. Except for context-specific music as described in the following paragraphs, tracks will play randomly from all available tracks (with a little bias to avoid close repetition of tracks). There is no overriding - a "thatched-villagers.mp3" in a mod will play in addition to and with the same likelihood as the file that the base game offers to download for you. There is no hard technical limit on bitrate or length, but large bandwidth requirements may lead to stuttering (The end of a "next turn", right before the world map is updated, and with very large maps, is the most likely to cause this).
+
+### Context-sensitive music: Overview
+The Music Controller will generally play one track after another, with a pause (can be changed in options) between. Leave-game confirmation dialog is opened playback will fade out and pause and can resume when it is closed.
+
+There are various 'triggers' in the game code initiating a choice for a new track. The new track will, if necessary, fade out the currently playing track quickly before it starts playing. Track choice involves context provided by the trigger and a random factor, and an attempt is made to not repeat any track until at least eight others have played.
+
+Mods can provide their own music folder, and if they are active its contents will be treated exactly the same as those in the main music folder. Mods should control usage of their tracks by careful choice of file name. Mod developers can watch console output for messages logging track choice with trigger parameters or loading errors.
+
+One track is special: The Thatched Villagers (see also credits.md). The game is able to download it if the music folder is empty, and it is played when the music volume slider is used. It is also a fallback track should certain problems occur (a broken file, however, will shut down the player until another trigger happens).
+
+### Context-sensitive music: List of Triggers
+Triggers indicate context (call it intent, mood, whatever, it doesn't matter) by optionally providing a prefix and/or suffix to match against the file name. There are a few flags as well influencing choice or behaviour - one flag function is to make prefix or suffix mandatory, meaning if no available file matches the track chooser will do nothing. Otherwise, a next track will always be chosen from the available list by sorting and then picking the first entry. Sorting is done by in order of precedence: Prefix match, Suffix match, Recently played, and a random number. Therefore, as currently no triggers have an empty prefix, files matching none of the prefixes will never play unless there are less than eight files matching the requested prefix.
+
+The current list of triggers is as follows:
+
+| Description | Prefix | M[^M] | Suffix | M[^X] | Flags |
+| ----------- |:------ |:---:| ----:|:---:|:---:|
+| Automatic next-track[^0] | | | Ambient | | |
+| Launch game[^1] | | | Menu | | |
+| Every 10th turn | (player civ name) | M | Peace or War[^2] | | F[^F] |
+| New game: Select a mod | (mod name) | M | Theme | | S[^S] |
+| New game: Pick a nation for a player | (nation name) | M | Theme or Peace | | S[^S] |
+| Diplomacy: Select player | (nation name) | M | Peace or War[^3] | | S[^S] |
+| First contact[^4] | (civ name) | M | Theme or Peace | M | |
+| War declaration[^5] | (civ name) | M | War | M | |
+| Civ defeated | (civ name) | | Defeat | M | |
+| Golden Age | (civ name) | M | Golden | M | N[^N] |
+| Wonder built | (wonder name) | M | Built | M | N[^N] |
+| Tech researched | (tech name) | M | Researched | M | N[^N] |
+| Map editor: Select nation start location | (nation name) | M | Theme | | S[^S] N[^N] |
+| Options: Volume slider or Default track downloaded | | | | | D[^D] |
+| Options: Click currently playing label[^6] | | M | Ambient | | S[^S] | 
+
+Legend:
+[^N]: **Not implemented**
+[^M]: Prefix must match. If no matching file is found, the trigger will do nothing.
+[^X]: Suffix must match. If no matching file is found, the trigger will do nothing.
+[^S]: Stop after playback. No automatic next choice.
+[^F]: Slow fadeout of replaced track.
+[^D]: Always plays the default file.
+[^0]: Whenever a track finishes and the configured silence has elapsed, an 'Ambient' track without any context is chosen. Also triggered by 'resume' (e.g. switching to another app and back on Android)
+[^1]: First opening of the Main Menu (or the initial language picker).
+[^2]: Whether the active player is at war with anybody.
+[^3]: According to your relation to the picked player.
+[^4]: Excluding City States.
+[^5]: Both in the alert when another player declares War on you and declaring War yourself in Diplomacy screen.
+[^6]: Yes these flags are not optimal.