From d26f3a779e428f6463db27aae107f2b45ae2fde9 Mon Sep 17 00:00:00 2001
From: Alex Lobascio <alex@Lobasc.io>
Date: Sun, 31 Aug 2025 14:55:59 -0700
Subject: [PATCH] add default queue_event_player events_when_finished:
 "queue_event_complete"

If the config provides events_when_complete, those are used instead.
The queue_event is included in either case, along with the optional args
provided in the config.
---
 mpf/config_players/queue_event_player.py      | 27 +++++++++++--------
 .../config/test_queue_event_player.yaml       |  2 ++
 mpf/tests/test_QueueEventPlayer.py            |  2 +-
 3 files changed, 19 insertions(+), 12 deletions(-)

diff --git a/mpf/config_players/queue_event_player.py b/mpf/config_players/queue_event_player.py
index ba886ba05..5fbd051ee 100644
--- a/mpf/config_players/queue_event_player.py
+++ b/mpf/config_players/queue_event_player.py
@@ -18,23 +18,28 @@ def play(self, settings, context, calling_context, priority=0, **kwargs):
         """Post queue events."""
         del kwargs
         del calling_context
-        if settings['events_when_finished']:
-            self.machine.events.post_queue(
-                settings['queue_event'],
-                callback=partial(self._callback,
-                                 settings['events_when_finished'],
-                                 settings['args']),
-                **settings['args'])
-        else:
-            self.machine.events.post_queue(settings['queue_event'],
-                                           **settings['args'])
+        queue_event = settings['queue_event']
+        events_when_finished = settings['events_when_finished'] or 'queue_event_complete'
+        self.machine.events.post_queue(queue_event,
+                                       callback=partial(self._callback,
+                                                        events_when_finished,
+                                                        queue_event=queue_event,
+                                                        **settings['args']),
+                                       **settings['args'])
+        '''event: queue_event_complete
+        desc: A queue event has completed and queue_event_player
+        is reporting completion with a default handler
+        args:
+        queue_event: The name of the queue event (not the queue event player entry)
+        **args: Any additional arguments defined in your queue_event_player under "args"
+        '''
 
     def validate_config_entry(self, settings, name):
         """Validate one entry of this player."""
         config = self._parse_config(settings, name)
         return config
 
-    def _callback(self, event, s):
+    def _callback(self, event, **s):
         self.machine.events.post(event, **s)
 
     def get_express_config(self, value):
diff --git a/mpf/tests/machine_files/event_players/config/test_queue_event_player.yaml b/mpf/tests/machine_files/event_players/config/test_queue_event_player.yaml
index 21122e17c..57248a92b 100644
--- a/mpf/tests/machine_files/event_players/config/test_queue_event_player.yaml
+++ b/mpf/tests/machine_files/event_players/config/test_queue_event_player.yaml
@@ -7,6 +7,8 @@ queue_event_player:
     play:
       queue_event: queue_event1
       events_when_finished: queue_event1_finished
+      args:
+        foo: bar
 
 queue_relay_player:
     relay.1:
diff --git a/mpf/tests/test_QueueEventPlayer.py b/mpf/tests/test_QueueEventPlayer.py
index 0b6dcea1b..9ed90200a 100644
--- a/mpf/tests/test_QueueEventPlayer.py
+++ b/mpf/tests/test_QueueEventPlayer.py
@@ -39,7 +39,7 @@ def test_queue_event_player(self):
 
         self.queue2.clear()
         self.advance_time_and_run()
-        self.assertEventCalled("queue_event1_finished")
+        self.assertEventCalledWith("queue_event1_finished", queue_event="queue_event1", foo="bar")
 
     def _cb(self, **kwargs):
         del kwargs