Migration guide for 0.57 to 0.80

docs/install/0.80.md

@@ -0,0 +1,62 @@
+---
+title: Notes for upgrading to MPF 0.80
+---
+
+# MPF 0.80 changes (GMC pre-release)
+
+*Last updated May 25, 2024*
+
+The upcoming release of MPF is 0.80, which includes support for the Godot Media Controller (GMC) and drops support for the 0.57 Kivy-based Media Controller (MC).
+
+While there are not many functional changes in MPF between 0.57 and 0.80, there are some config file migrations necessary and this document will help you through that.
+
+*See also: [Installing MPF 0.80 and the GMC](../gmc/installation.md)*
+
+## List of Required Changes
+
+### Bonus
+
+The bonus config spec has changed to use the keyword `entry` instead of `event` when defining bonus entries, because Bonus events have changed to use a consolidated *bonus_entry* event instead of unique events for each bonus item (including subtotal, multiplier, and total).
+
+In your bonus.yaml config section, change each entry from `event: bonus_item_name` to `entry: bonus_item_name`.
+
+With this change, given a bonus entry named "completed_ramps" that was hit 3 times for a score of 3000:
+
+**MPF 0.57 Event:**
+```
+    completed_ramps{hits=3, score=3000}
+```
+
+**MPF 0.80 Event:**
+```
+    bonus_entry{entry="completed_ramps", hits=3, score=3000}
+```
+
+
+### Carousel
+
+Carousel events have changed to use a consolidated *item_highlighted* event instead of unique events for each item.
+
+Given a carousel mode "missionselect" and an item "garrus":
+
+**MPF 0.57 Event:**
+```
+    missionselect_garrus_highlighted{direction="forwards"}
+```
+
+**MPF 0.80 Event:**
+```
+    item_highlighted{carousel="missionselect", item="garrus", direction="forwards"}
+```
+
+The new *item_highlighted* event is incorporated into GMC, but if you have other custom event handlers for carousel item selection those will need to be updated.
+
+### Slides and Widgets
+
+The GMC manages all slides and widgets, so the `slides:` and `widgets:` config sections are deprecated.
+
+### Sound Player
+
+The GMC manages all sound assets, so the `sound_system:` and `sounds:` config sections are deprecated. You can still reference sounds by filename directly, but if you want to specify specific settings for a sound or sound pool, use the `MPFSoundAsset` resource type in GMC.
+
+Audio channel groups have been renamed from "tracks" to "buses", so in your `sound_player:` config sections change `track: music` to `bus: music`.

docs/install/index.md

@@ -111,6 +111,10 @@ If you are installing MPF 0.57 to continue work on an existing MC-based project,
 * [Windows](windows.md)
 * [Linux](linux)
 
+## Migrating MPF 0.57 to MPF 0.80
+
+If you have an existing MPF 0.57 project and would like to use MPF 0.80 and the GMC, there are just a few config changes needed. See the [MPF 0.80 Migration Guide](./0.80.md) for instructions.
+
 ## Next step: The Tutorial!
 
 We have a tutorial which walks you through the first few steps of getting