Documentation for sounds

docs/gmc/installation.md

@@ -68,8 +68,12 @@ When successful, you should see a new *mpf-gmc* folder in the *addons* folder yo
 
 In the Godot Editor, open the *Project > Project Settings* menu and select the *Plugins* tab. You should see an option there for **Godot MC**, check the checkbox to enable the plugin.
 
+![image](images/project_settings_plugins.png)
+
 Now go to the *Autoload* tab and click the folder icon to select an Autoload script. Navigate to the *addons/mpf-gmc* folder and choose the file *mpf_gmc.md*. Under *Node Name* set the name to "MPF" (all caps) and press *Add*. You should see a new line appear with a checkbox enabled.
 
+![image](images/project_settings_autoload.png)
+
 !!! warning
 
     Godot exposes autoloads by the given Node Name, and various components of GMC reference one another by the name "MPF". When adding the *mpf_gmc.md* autoload, you _must_ set the Node Name to **MPF** or the GMC will not function.

docs/gmc/reference/mpf-sound-asset.md

@@ -0,0 +1,56 @@
+---
+title: MPFSoundAsset
+---
+
+# MPFSoundAsset
+
+`MPFSound` is a Godot Node class provided by the MPF-GMC extension. It provides the same options as `sound_player` for configuring playback, with the convenience of coding those options once rather than on each `sound_player` call.
+
+In the Godot Editor *FileSystem* panel, find an appropriate *sounds* folder and right click to *Create New > Resource > MPFSoundAsset*. Choose a name for the sound that you'll use to call it from `sound_player` and save the file.
+
+!!! note "Sound name uniqueness"
+
+    Each sound resource needs a unique name so GMC can find it when referenced by `sound_player`. It's okay to create an MPFSoundAsset and save it with the same name as the sound file. GMC maps all sound files first and then all resources, so a resource with the same name will override the sound file.
+
+
+## Node Configuration
+
+In the *Inspector* tab on the right side, you can configure the `MPFSoundAsset` with these options.
+
+!!! note
+
+    Options configured in the `MPFSoundAsset` will be the defaults for this sound, but can be overridden with values in `sound_player` for different behavior when needed.
+
+### file:
+
+Single value, type: `Resource`. Default: `None`
+
+This is the sound file or sound resource that will be played for this sound's name. It can be a single sound file (WAV, OGG), or any `AudioStream`-based resource in the project (`AudioStreamRandomizer`, `AudioStreamPlaylist`, etc).
+
+### bus:
+
+Single value, type: `String`. Default: `None`
+
+The name of the bus this sound will play on.
+
+### fade_in:
+
+Single value, type: `float`. Default: `0.0`
+
+The number of seconds over which this sound will fade in when it is played.
+
+### fade_out:
+
+Single value, type: `float`. Default: `0.0`
+
+The number of seconds over which this sound will fade out when it is stopped.
+
+### start_at:
+
+Single value, type `float`. Default: `0.0`
+
+The timecode (in seconds) where playback of this sound should start when it is played.
+
+## Methods
+
+`MPFSoundAsset` does not have any public methods exposed.

docs/gmc/slides.md

@@ -1,5 +1,5 @@
 ---
-title: MPFSlide
+title: GMC Slides
 ---
 
 # GMC Slides

docs/gmc/sound.md

@@ -0,0 +1,51 @@
+---
+title: GMC Sounds
+---
+
+# Sound Playback in GMC
+
+All sounds in GMC are managed through Godot, but MPF can be used to trigger playback actions through the `sound_player` config settings.
+
+All sound files (including resource files) must be placed in either a */sounds* folder in the project root, or in */modes/<mode_name>/sounds* folder in any mode. Subfolders within these folders are allowed as well.
+
+## Sound Resources: Files, Native, and Custom Types
+
+GMC supports playback of sounds from a variety of different resource types interchangably. This allows you to quickly and conveniently play back back sounds from file reference, while also allowing custom sound behavior and advanced sound features by referencing a Godot resource file.
+
+### Direct File Playback
+
+If you just want to play a sound, you can reference that sound by its file name (without extension) in the `sound_player`.
+
+For example, if you have files in your project called *frenzy_background_music.ogg* and *small_explosion_one.wav* you could trigger those sounds with the following config:
+
+``` yaml
+
+    sound_player:
+        mode_frenzy_started:
+            frenzy_background_music:
+                bus: music
+                fade_in: 500ms
+                fade_out: 1s
+        drop_targets_complete: small_explosion_one
+
+```
+
+### MPFSound Resource
+
+GMC includes a custom class called `MPFSound` that provides properties that can be saved to a resource file. When this resource is played, the playback properties are read from the file and don't need to be passed as part of the `sound_player` config.
+
+This is a convenient way to keep the same settings for a sound file without having to specify it every time it's called in `sound_player`.
+
+More details on can be found on the [MPFSound Reference Doc](reference/mpf-sound.md).
+
+### Other Godot Resources
+
+Any Godot class that derives from [`AudioStream`](https://docs.godotengine.org/en/stable/classes/class_audiostream.html) can also be used as a sound resource as long as its in one of the *sounds* folders.
+
+[**AudioStreamRandomizer**](https://docs.godotengine.org/en/stable/classes/class_audiostreamrandomizer.html#class-audiostreamrandomizer) can be used to create a sound pool with randomized playback of any number of sounds, and/or randomized pitch and volume for quick variations on a base set of sounds to reduce repetition.
+
+[**AudioStreamPolyphonic**](https://docs.godotengine.org/en/stable/classes/class_audiostreampolyphonic.html#class-audiostreampolyphonic) can be used to stack multiple playbacks of the same sound in a single stream rather than instantiating a separate sound playback instance for each one.
+
+[**AudioStreamSynchronized**](https://docs.godotengine.org/en/latest/classes/class_audiostreamsynchronized.html#class-audiostreamsynchronized) *(coming in Godot 4.3)* can be used to layer and synchronize multiple sound files for seamless playback mixing.
+
+[**AudioStreamPlaylist**](https://docs.godotengine.org/en/latest/classes/class_audiostreamplaylist.html#class-audiostreamplaylist) *(coming in Godot 4.3)* can be used to create playlists of sound files that can be played back, shuffled, cross-faded, and looped.

mkdocs.yml

@@ -613,8 +613,10 @@ nav:
     - Installation: gmc/installation.md
     - Setup: gmc/setup.md
     - Slides: gmc/slides.md
+    - Sound: gmc/sound.md
     - Config Reference:
       - gmc/reference/index.md
+      - MPFDisplay: gmc/reference/mpf-display.md
       - MPFSlide: gmc/reference/mpf-slide.md
       - MPFWindow: gmc/reference/mpf-window.md