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 NO 🚫

The auditor: section of the machine configuration file lets you control what events the MPF's auditor module includes in its audits.

Here's an example which is the settings we including in the default mpfconfig.yaml file. (So these are the settings that are included by default with every game you run.) Also, by default, the auditor saves its audits to /audits/audits.yaml in the folder for each machine. (Check out the documentation on the Auditor to see a sample audit log file.)

  save_events: ball_ended game_ended
  audit: shots switches events player
  events: ball_search_begin machine_init_phase_1 game_started game_ended machine_reset
  player: score
  num_player_top_records: 10

Optional settings

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


List of one (or more) values, each is a type: string. Defaults to empty.

This is a list of the various types of things you want to include in your audit file. There are currently four options:

  • shots - tracks the number of times each shot has been made
  • switches - tracks the number of times each switch has been hit.
  • events - whether the auditor should audit certain events. (Add the events you want to track to the events section.)
  • player - includes player variables (score, maybe shots or goals they've achieved, etc.) See the player section below for details.


List of one (or more) events. The device will add handlers for those events. Defaults to empty.

A list of which events you want to audit. These are the names of any events you want.


Single value, type: integer. Default: 1

For player-specific variables, you have the option of track the "top" number of each. So in the example above, since the only player item is score, the auditor will track the top 10 highest scores, plus the total count and the overall average.


List of one (or more) values, each is a type: string. Defaults to empty.

A list of player variables you want to audit. The auditor will save a certain number (configurable via the num_player_top_records: setting), as well as the total number of entries and the current average.


List of one (or more) events. The device will add handlers for those events. Default: auditor_reset,factory_reset

Events to reset audits in the machine. This is used by the service mode.


List of one (or more) device control events (Instructions for entering device control events). Default: ball_ended

Default: ball_ended

Events in this list, when posted, trigger the auditor to save its audits to disk.

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