update carousel events per missionpinball/mpf#1907

bosh · bosh · commit a2178f216bc3 · 2025-08-31T16:58:07.000-07:00
diff --git a/docs/cookbook/carousel.md b/docs/cookbook/carousel.md
@@ -74,7 +74,7 @@ start the mode that was selected by the player.
 #config_version=5
 mode:
   start_events: ball_starting
-  stop_events: my_carousel_item_selected
+  stop_events: carousel_item_selected{carousel=my_carousel}
   code: mpf.modes.carousel.code.carousel.Carousel
   use_wait_queue: true
 mode_settings:
diff --git a/docs/events/carousel/index.md b/docs/events/carousel/index.md
@@ -10,7 +10,9 @@ See: [Carousel Mode Selection](../../cookbook/carousel.md) for pre-0.80 carousel
 
 See: [MPFCarousel](../../gmc/reference/mpf-carousel.md) for 0.80+ carousel configuration.
 
-* [item_highlighted](../item_highlighted.md) *Note: 0.80+ only*
-* [(carousel_name)\_items_empty](../carousel_name_items_empty.md)
-* [(carousel_name)\_(item_name)\_selected](../carousel_name_item_name_selected.md)
-* [(carousel_name)\_item_selected](../carousel_name_item_selected.md)
+The following events are as of MPF `0.80.0.dev10`.
+Previously, the word "carousel" was replaced with the actual carousel name, along with other differences.
+
+* [carousel_item_highlighted](../carousel_item_highlighted.md)
+* [carousel\_items_empty](../carousel_items_empty.md)
+* [carousel\_item_selected](../carousel_item_selected.md)
diff --git a/docs/events/carousel_item_highlighted.md b/docs/events/carousel_item_highlighted.md
@@ -1,8 +1,8 @@
 ---
-title: item_highlighted
+title: carousel_item_highlighted
 ---
 
-# item_highlighted
+# carousel_item_highlighted
 
 
 --8<-- "event.md"
diff --git a/docs/events/carousel_item_selected.md b/docs/events/carousel_item_selected.md
@@ -0,0 +1,26 @@
+---
+title: carousel_item_selected
+---
+
+# carousel_item_selected
+
+
+--8<-- "event.md"
+
+A carousel has just had an item selected. Use the carousel and item
+keyword arguments to filter this event in your config players and handle
+the different item selection behaviors.
+
+## Keyword arguments
+
+(See the [Conditional Events](overview/conditional.md)
+guide for details for how to create entries in your config file that
+only respond to certain combinations of the arguments below.)
+
+#### `carousel`:
+
+The name of the carousel that had an item selected.
+
+#### `item`:
+
+The string name of the selected item.
diff --git a/docs/events/carousel_items_empty.md b/docs/events/carousel_items_empty.md
@@ -0,0 +1,26 @@
+---
+title: carousel_items_empty
+---
+
+# carousel_items_empty
+
+
+--8<-- "event.md"
+
+A carousel determined that it has
+no selectable_items that are valid for display. This can be because
+the `mode_settings` for the carousel mode still needs to be set,
+or because all of the `selectable_items` were dynamically evaluated
+and removed from the valid option set. Use the `carousel` keyword
+argument to filter on the correct carousel if have any config player
+behaviors that need to happen in response.
+
+## Keyword arguments
+
+(See the [Conditional Events](overview/conditional.md)
+guide for details for how to create entries in your config file that
+only respond to certain combinations of the arguments below.)
+
+#### `carousel`:
+
+The name of the carousel that had an item selected.
diff --git a/docs/events/carousel_name_item_name_selected.md b/docs/events/carousel_name_item_name_selected.md
diff --git a/docs/events/carousel_name_item_selected.md b/docs/events/carousel_name_item_selected.md
diff --git a/docs/events/carousel_name_items_empty.md b/docs/events/carousel_name_items_empty.md
diff --git a/docs/events/index.md b/docs/events/index.md
@@ -289,10 +289,9 @@ will posted an event called *switch_s_left_slingshot_active*.
     * [bonus_subtotal](bonus_subtotal.md)
 
 * [Carousel Events](carousel/index.md)
-    * [item_highlighted](item_highlighted.md)
-    * [(carousel_name)\_items_empty](carousel_name_items_empty.md)
-    * [(carousel_name)\_(item_name)\_selected](carousel_name_item_name_selected.md)
-    * [(carousel_name)\_item_selected](carousel_name_item_selected.md)
+    * [carousel_item_highlighted](carousel_item_highlighted.md)
+    * [carousel\_items_empty](carousel_items_empty.md)
+    * [carousel\_item_selected](carousel_item_selected.md)
 
 * Config Player Events
     * [clear](clear.md)
diff --git a/docs/gmc/reference/mpf-gmc.md b/docs/gmc/reference/mpf-gmc.md
@@ -115,7 +115,7 @@ Emitted during the Bonus mode. See [bonus mode settings](bonus.md) for details.
 
 Emitted when a mode ends.
 
-#### `item_highlighted(payload)`
+#### `carousel_item_highlighted(payload)`
 
 Emitted during a carousel event.
 
diff --git a/docs/install/0.80.md b/docs/install/0.80.md
@@ -35,7 +35,7 @@ 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.
+Carousel events have changed to use a consolidated *carousel_item_highlighted* and *carousel_item_selected* event instead of unique events for each item.
 
 Given a carousel mode "missionselect" and an item "garrus":
 
@@ -46,10 +46,10 @@ missionselect_garrus_highlighted{direction="forwards"}
 
 **MPF 0.80 Event:**
 ``` console
-item_highlighted{carousel="missionselect", item="garrus", direction="forwards"}
+carousel_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.
+The new *carousel_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
 
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -1211,10 +1211,9 @@ nav:
       - bonus_subtotal: events/bonus_subtotal.md
     - Carousel Events:
       - events/carousel/index.md
-      - carousel_name_items_empty: events/carousel_name_items_empty.md
-      - carousel_name_item_name_selected: events/carousel_name_item_name_selected.md
-      - carousel_name_item_selected: events/carousel_name_item_selected.md
-      - item_highlighted: events/item_highlighted.md
+      - carousel_name_items_empty: events/carousel_items_empty.md
+      - carousel_name_item_selected: events/carousel_item_selected.md
+      - carousel_item_highlighted: events/carousel_item_highlighted.md
     - Config Player Events:
       - clear: events/clear.md
     - Credit Events:
