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 keyboard: section of your config is used to configure options for how you map computer keyboard keys to pinball machine switches and events. This is useful for testing your game from your computer when you're not around your physical machine.

You might also want to implement some virtual switches in your machine which can be only used via a keyboard for debugging.

Options for each key & key combination

Once you enter the key and/or key combination, then you need to create a subsection which defines what this key or key combination does when it's hit. There are several options:

Optional settings

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


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

Help us write it!

This section is unwritten or needs an update or edit. Can you help write it? Get your name in lights and geeky pinball bragging rights! Hit the magic sparkly wand to the right of the title to see this page source on GitHub. Then add/edit and submit your change. It's easy!


Single event. This device will be posted by the device. Defaults to empty.

You can specify an event name to be posted when this key is pressed. This is useful for testing when you want to test some part of your game code based on an event. For example, you could map a keyboard key to clockwise_orbit_hit event instead of having to hit the left_orbit_enter key quickly followed by the right_orbit_enter key. Events entered here are transmitted posted by the MPF core engine process.


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

If True, then this key is inverted, meaning the associated switch is active when you're not pushing the key down, and it's inactive when you're holding the key.


Single event. This device will be posted by the device. Defaults to empty.

This is similar to the event: entry, except an mc_event is posted as events in the media controller process, rather than in the MPF process.


One or more sub-entries. Each in the format of string : string

This section contains subsections which are a list of parameters that are posted along with the event or mc_event specified above. Using the following configuration file snippet as an example:

    event: advance_reel_test
      reel_name: score_1p_10
      direction: 1

This keyboard entry will post the event advance_reel_test when the 4 key is pressed, and it will pass the parameters reel_name=score_1p_10 and direction=1.


Single value, type: string name of a switches: device. Defaults to empty.

The switch name of the pinball machine switch you want this key (or key combination) to control.


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

If True, then the key acts like a "push on / push off" key, where you just have to tap it once to hold the switch active. This is useful for switches in ball devices, since you don't want to have to hold down the keys on your keyboard forever whenever a ball is locked in a device. Default is False. You might want to create multiple entries for the same switch for different key combinations. For example:

#! keyboard:
    switch: trough1
    switch: trough1
    toggle: true

In the above code, you can momentarily "tap" the trough1 switch by hitting the 1 key, but if you want to lock that switch on, then you can push Shift+1.

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