Skip to content

Types of events

There are several different types of events in MPF, including:

  • Basic
  • Queue

You can find the details of how to use each of these events by reading through the API documentation for the event manager, but here's a quick overview.

Video about events in MPF:

Basic Events

The basic event is a simple event with a name (and possibly keyword argument pairs) that is posted.

The event manager will call the registered handlers one-by-one in the order of their priority (from when they registered).

Queue Events

Queue events are similar to basic events, except that the event won't actually finish until all the handlers say it's ok to do so.

The game_ending event is an example of a queue event. When the game is over, game_ending is posted, and when that's done, game_ended is posted and the attract mode starts again. However there are several modes that might want to "block" the completion of game_ending until they can do whatever they need to do. For example, if match is enabled, it will want to block game_ending until it can run the match animation. If a player has achieved a high score, the high score mode will want to block game ending, etc.

You can create your own queue events with the queue_event_player: and queue_relay_player: config file sections.

Queue Events are categorized in the Events Reference by their device or other grouping type, but are also listed together in the Queue Events event listing page.

Boolean Events

Boolean events are special events that allow their handlers to decide whether to continue or cancel a behavior. Each handler is called in order, and if any handler returns False, the processing will stop and the code that posted the event will resolve the False pathway.

For example, the event request_to_start_game is a boolean event posted attract mode when the start button is pressed. Many MPF subsystems, such as ball management and credit management, listen for this event, and report whether the game is not able to add another player.

The boolean event player_add_request is a common one that interactive menus and carousels need to intercept. If you use the start button as a "select" interaction, you may want to ensure that the same button press is not considered to be a player add request. To intercept this, you can use the python snippet:

from mpf.core.mode import Mode

class MyMode(Mode):
  def mode_start(self, **kwargs):
    """Intercept player_add_request."""
    self.add_mode_event_handler('player_add_request', self._player_add_request)

  def _player_add_request(self, **kwargs):
    """Block player adds during carousel modes."""
    return False

Place the python file in your mode's code/ subfolder. In your mode YAML, add the code: to load the python:

#config_version=6

mode:
  code: my_mode.MyMode

Note for Programmers

If you're a programmer and familiar with Python, you'll notice in the source code that there are more types of events than just basic and queue events. The basic and queue events are the only ones that are exposed via config files, but you'll notice there are boolean and relay events, and that there are asynchronous versions of all events too. See the API reference for details.

Something missing or wrong? You can fix it!

This website is edited by people like you! Is something wrong or missing? Is something out of date, or can you explain it better?

Please help us! You can fix it yourself and be an official "open source" contributor!

It's easy! See our Beginner's guide to editing the docs.

Page navigation via the keyboard: < >

You can navigate this site via the keyboard. There are two modes:

General navigation, when search is not focused:

  • F , S , / : open search dialog
  • P , , : go to previous page
  • N , . : go to next page

While using the search function:

  • Down , Up : select next / previous result
  • Esc , Tab : close search
  • Enter : go to highlighted page in the results