Skip to content

bonus (mode_settings:)

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 NO 🚫
mode config files YES ✅

This section explains how to use the mode_settings: section for your machine's End of Ball Bonus mode. You should probably read the full End of Ball Bonus documentation first, and then just use this for a reference for the settings later.

Note that the "mode_settings:" section is pretty much a generic placeholder that any mode can use for its own custom settings. So the settings described here are specifically the settings that are used by MPF's built-in bonus mode, and so these settings are only valid in the bonus mode's mode configuration file.

Here's an example from Brooks 'n Dunn:

##! mode: mode1
mode_settings:
  display_delay_ms: 4000
  hurry_up_delay_ms: 500
  hurry_up_event: flipper_cancel
  bonus_entries:
    - event: quarter_bonus
      score: current_player.quarters * current_player.album_value
    - event: wizard_bonus
      score: 25000
      player_score_entry: num_albums

Settings

display_delay_ms:

Time value, default 2s

The time between each "display event" generated by the bonus mode when its running. (In other words, this is essentially how long each bonus slide is shown.) This can be overridden on a slide-by-slide basis.

hurry_up_delay_ms:

Time value, default 500ms

The time between each "display event" after the bonus "hurry up" mode has been triggered. So if the display_delay_ms: is 2 seconds, and then the player hits both flippers at the same time to "hurry up" the bonus display, that hurry up time will be used here.

Note that if you don't want to show the slides faster, rather you just want to jump directly to the last slide, then you can enter a value of 0 here.

hurry_up_event:

Name of an event. Default is flipper_cancel.

The event that will cause the bonus mode to change its delay between slides from the display_delay_ms: time to the hurry_up_delay_ms: time. When this event is posted, the next slide is shown immediately, and the timing is set to the new hurry up value.

end_bonus_event:

Name of an event. Default is None.

If you enter an event name here, the bonus mode will pause before posting its bonus_done event and wait for this event to be posted. If this event is None, then the bonus mode will automatically end. You can enter an event name here if you have something custom you want to do in the bonus mode.

keep_multiplier:

Boolean True/False or Yes/No. Default is False.

Controls whether the bonus_multiplier player variable should be reset (to 1) when the bonus mode is over. Default is False which will not keep the bonus. (e.g. default is to reset it). Conditional values are supported.

Also note that you can use dynamic values here if you want to do math or use settings to make this configurable.

bonus_entries:

A list of sub-entries, with one entry for each "thing" you want to track in the bonus.

This is the real meat of the bonus section. Many modern pinball machines have lots of different things that go into the bonus calculation. So rather than just saying, "Your bonus is 5400 points", it's more like "5 aliens x 25k points each, plus 15 modes x 1m each, plus 4 combos x 100k each, all times the bonus multiplier."

Since this section is entered like a list, you need a dash and a space at the beginning of each new entry so MPF knows where one entry ends and one begins.

Here's how an example might look based on the aliens, modes, and combos example just mentioned:

bonus_entries:
  - event: alien_bonus
    score: 25000
    player_score_entry: aliens
  - event: mode_bonus
    score: 1000000
    player_score_entry: num_modes
  - event: combo_bonus
    score: 100000
    player_score_entry: combos

Let's look at each option you can use in each bonus entry:

event: (required)

The name of the event that is posted by the bonus mode. You should use a slide_player: in your bonus mode with slide entries based on these names, so when the bonus mode posts that event, you can show a slide with the relevant information for that bonus entry.

score: (required)

How many points this bonus entry is worth. Note that this will be multiplied by the player_score_entry: (if it's present). Also note that you can use dynamic values here if you want to do advanced math.

player_score_entry:

An optional name of a player variable that will be multiplied by the score: entry. This is useful for the "easy" entries where it's just "some player variable multiplied by some score". (For example, "number of aliens times 25,000".) In the example above, the first entry called "alien_bonus" will multiply the "aliens" player variable times 25000.

Note that the bonus mode doesn't care what player variable you use, and it would be up to you to make sure that the player variable you choose is updated throughout your game (either through a variable_player: section or a logic block or something like that).

Also if you choose not to include this entry, that's fine. In that case the score: entry will be used by itself. Notice in the example at the top of this page from Brooks 'n Dunn that it's not used when we need the advanced math of multiplying two player variables together.

reset_player_score_entry:

Boolean (True/False or Yes/No). Default is False.

If this is true/yes, then the bonus mode will reset the player_score_entry: back to 0 once the bonus mode is over. This is just a convenience thing for simpler bonus calculations that need to be reset per ball. You don't have to use it can could also reset the player variable some other way.

skip_if_negative:

Boolean (True/False or Yes/No). Default is False.

If this is True/Yes and if the score calculation for this bonus entry is less than 0, the event for this bonus entry is not posted and the value is not subtracted from the player's score.

skip_if_zero:

Boolean (True/False or Yes/No). Default is True.

If this is True/Yes, then if the score calculation for this bonus entry turns out to be 0, then the event for this bonus entry is not posted. This is nice if you don't want a bonus screen to show up for something the player has not done, like "0 ramps = 0 points" or whatever. (Or maybe you want to make this "true" to show the player how bad they are?) :)

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