diff --git a/docs/install/0.80.md b/docs/install/0.80.md new file mode 100644 index 0000000000..5fcb43560f --- /dev/null +++ b/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`. \ No newline at end of file diff --git a/docs/install/index.md b/docs/install/index.md index 7183b939cc..5c3940301c 100644 --- a/docs/install/index.md +++ b/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