Skip to content


This is a config file reference. Click for instructions.

This page is reference material which explains every setting and option for this section of an MPF yaml config file. See the instructions for config files for formatting and other details. See our guide to config file examples for more examples of real configs in action.

Valid in
machine config files YES ✅
mode config files YES ✅


This section can also be used in a show file in the random_events: section of a step.

The random_event_player: section of your config is where you can play a random event out of a list based on an event.

# in your global config:
    scope: machine
      - event1
      - event2
      - event3
##! mode: base
# in your mode:
      - event1
      - event2
      - event3
      unlikely_event1: 2
      unlikely_event2: 3
      likely_event1: 45
      likely_event2: 50
      event1{}: 25
      event2{device.ball_devices.bd_ramp_lock.balls==2}: 25
      event3{device.accruals.base_locking_engaged.completed}: 10
      event4{>9}: 30
      event5{current_player.hearts < current_player.hearts_max}: 10
    fallback_event: event_posts_if_everything_above_false

Optional settings

The following sections are optional in the random_event_player: section of your config. (If you don't include them, the default will be used).


Single value, type: boolean (true/false). Default: false

Disable random.


Unknown type. See description below.

List the events to choose from. If you use a list all events will be equiprobable. You can also use a dict with eventname: probablity. See the example above.

You can also use conditional events here.


Single value, type: string. Defaults to empty.

If all of the events in the random_event_player are conditional and none of them are true, this event name will be posted instead. If not defined, no event will be posted.


Single value, type: boolean (true/false). Default: true

Enforce that all events are posted once before a event is posted a second time.


Single value, type: boolean (true/false). Default: true

If set to true it will enforce that the same entry will never appear twice in a row. When setting force_all to true this will prevent that the last event is the same as the first of the next iteration.


Single value, type: one of the following options: player, machine. Default: player

The scope of the random selection for force_different and force_all. When setting to player this is enforced per player and persisted between balls.

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