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 ✅

The variable_player: section of your mode config lets you add, subtract, or replace player variables based on events that are posted.

At the most basic level, you can use this to add to a player's score (which is technically adding value to the player variable called score), but in reality you can affect any player or machine variable.

Here's an example:

##! mode: mode1
    score: 1000     # adds 1000 to the player's "score" variable
    score: 10000    # adds 10,000 to the player's "score" variable
    ramps: 1        # adds 1 to the player's "ramps" variable
      int: 0          # sets the player's "ramps" variable to 0.
      action: set     # means that this event will "set" (or reset) the variable to the value, rather than add to it
      int: 25000 * current_player.ramps     # multiplies the value of the current player's "ramps" variable by 25,000 and adds the result to the player's "score" variable
      block: true      # "blocks" this event from being passed to variable player sections from lower-priority modes
      string: RUBY     # Sets the player's "treasure_name" variable to a string called "RUBY"

See Variable player for details.


Like many sections of MPF configs, the variable_player: section format is generically setup like this:


The following settings can be used with each event section listed in your variable_player section:


You can include any player variable under an event to add numeric value to that variable. (If the variable doesn't exist, it will set the player variable to that.) For example:

##! mode: mode1
    score: 1000
    aliens: 1
    bonus: 10

The above config will add 1000 to the "score" player variable, 1 to the "aliens" player variable, and 20 to the "bonus" player variable when the event called some_event is posted. Note that you don't even need to include a "score" if you just want to add to other player vars.

Note that you can use a dynamic value for this setting too, which means you can pull in values from other player variables, device states, etc. and do math on them.

Optional settings

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


Single value, type: one of the following options: add, set, add_machine, set_machine. Default: add

By default, the variable player entries will be added to the existing value of a player variable. If you want to replace or reset the value of the player var, you can add action: set to the entry. However to do this, you have to indent that setting under the player var name, and then specify the value in the "int:" section. For example, if you want the example from the above section to reset the aliens player variable to 1 instead of adding 1 to the current value, it would look like this:

##! mode: mode1
    score: 1000
    aliens:           # the player var you want to reset
      int: 1          # the integer value you're resetting this player var to
      action: set     # means you're resetting it, rather than adding to it
    bonus: 10

Starting in MPF 0.33, you can also add and set machine variables, by specifying action: add_machine or action: set_machine. In these cases the machine variable is specified just like the player variable in the "set" example above.


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

This is useful if you have a shot in a base mode that scores 500 points, but then in some timed mode you want that shot to be 5,000 points but you don't also want the base mode to score the 500 points on top of the 5,000 from the higher mode.

Note that when you use block, you also have to include the int:, float:, or string: setting indented. For example:

##! mode: mode1
      int: 5000
      block: true

There is also a shorthand way:

##! mode: mode1
    score: 5000|block


Single value, type: number or template (will be converted to floating point; Instructions for entering templates). Defaults to empty.

Adds or sets a player or machine variable to the specified float value. The int: setting takes priority over the float: setting so if both are present only the int: will be used. You can use placeholders which evalute to float as well.


Single value, type: integer or template (Instructions for entering templates). Defaults to empty.

Adds or sets a player or machine variable to the specified integer value (this is the most common use of the variable_player). The int: setting takes priority over the float: setting so if both are present only the int: will be used. You can use placeholders which evalute to int as well.


Single value, type: integer. Defaults to empty.

##! mode: mode1
      int: 1000
      player: 2
##! test
#! start_two_player_game
#! start_mode mode1
#! assert_player_variable 0 score
#! post add_score_to_player_2
#! assert_player_variable 0 score
#! drain_all_balls
#! assert_player_variable 1000 score

If the player: setting is not used, then this variable_player entry will default to the current player.


Single value, type: template_str. Defaults to empty.

Here's an example from Brooks 'n Dunn where there is a player variable (set via a counter) which tracks the player's current album value. We use the variable_player section tied to the events posted when the player variable changes and conditional events to set the current name of the album value, like this:

##! mode: mode1
      string: SILVER
      string: GOLD
      string: PLATINUM
      string: DOUBLE PLATINUM
      string: OFF THE CHARTS!

The above config lets us always have a player var called "album_name" we can use in slides and widgets which matches the value of the album, and it's automatically updated whenever the player var "album_value" changes.

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