Skip to content

Using dynamic runtime values in config files

MPF config files can contain values in the form of links to dynamic placeholders which are evaluated live when MPF is running rather than being hard-coded into a config file.

Dynamic values can come from several sources, including player variables, machine variables, operator settings, properties of devices, etc. (Read on for a full list.)

For example, you might want to have a shot called "jackpot" that scores a multiplier which is the number of shots made times 100k points.

Without dynamic values, your variable_player (scoring) section would be static, like this:

##! mode: mode1
    score: 100000

But let's say you have a player variable called "troll_hits" which holds the number of trolls hit that you want to multiply by 100,000 when the shot is made. You can use the "current_player" dynamic value in your variable_player config like this:

##! mode: mode1
    score: current_player.troll_hits * 100000

You can access other values dynamically as well, such as a timer ticking away a hurry-up or a counter to track how many times a multiplier switch has been hit

##! mode: mode1
    score: 1000 * device.timers.hurryup_clock.ticks_remaining * device.counters.hurryup_multiplier.value

Another example might be operator settings. Rather than hard coding tilt warnings to 3, you might want to like the operator choose the tilt warnings.

So instead of this:

##! mode: tilt
# in your tilt mode
  warnings_to_tilt: 3

You would have this instead:

# in your machine config
    label: Number of tilt warnings
      0: "no warnings"
      1: "1"
      2: "2"
      3: "3"
      5: "5"
      10: "10"
    default: 3
    key_type: int
    sort: 600
##! mode: tilt
# in your tilt mode
  warnings_to_tilt: settings.warnings_to_tilt

Note the example above requires that you have a settings: section in your machine config and that you've defined a setting called "tilt_warnings". See Tilt for more details.

You can also use dynamic values in conditional events.

Types of dynamic values

You can use the following types of placeholders.

Current Player Variables

You can access a player variable X of the current player using current_player.X. For instance, current_player.my_player_var will access my_player_var of the current player. This placeholder is only available when a game is active.

Common player variables are:

  • current_player.score - Score of the current player
  • current_player.ball - Current ball

Player Variables of Specific Player

You can access a player variable X of a specific player P using players[P].X. P starts at 0. So player 1 will be players[0].P. For instance, players[1].my_player_var will access my_player_var for player 2. players[0].my_player_var will access player 1. This placeholder is only available when a game is active.

Common player variables are:

  • players[0].score - Score of player 1
  • players[1].score - Score of player 2
  • players[2].score - Score of player 3
  • players[3].score - Score of player 4

Game Variables

You can access game variable X using game.X. This placeholder is only available when a game is active.

Common game variables are:

  • game.max_players - Maximum players currently allowed
  • game.num_players - Number of players in game
  • game.balls_per_game - Balls per game
  • game.balls_in_play - Balls in play
  • game.tilted - True if the game has been tilted
  • game.slam_tilted - True if the game has been slam tilted

Additionally, a game has all common mode variables (see below). game.X is just a convenient way to access

Machine Variables

You can access machine variable X using machine.X.

Common machine variables are:

  • machine.player1_score - Player 1 score from the last game
  • machine.player2_score - Player 2 score from the last game
  • machine.player3_score - Player 3 score from the last game
  • machine.player4_score - Player 4 score from the last game
  • machine.credits_string - String for credits or freeplay
  • machine.credits_value - Human readable credits string


You can access setting X using settings.X.


You can access property X of device D of type T using device.T.D.X. For instance you can access the value of counter my_counter using device.counters.my_counter.value.

Common device properties are:

  • device.counters.my_counter.value
  • device.counters.my_counter.enabled
  • device.flippers.left_flipper.enabled
  • device.playfields.playfield.balls
  • device.ball_devices.my_lock.balls
  • device.counters.superjets_counter.value
  • device.accruals.magic_tokens.enabled
  • device.sequences.world_tour.completed

MPF uses consistent names across devices, so for example any device that tracks a number will have a value property and any device that can be enabled/disabled will have an enabled property. The full list of properties available for a specific device are listed in the "Monitorable Properties" section of that device's documentation page.


You can access property X of mode M using mode.M.X.

Common mode properties are:


Using if/else logic with dynamic values

##! mode: mode1
    count_events: count_up
    count_complete_value: 5 if player.wizard_complete else 3

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