bonus (mode_settings:)

Config File section

Valid in machine config files NO
Valid in 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_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 show.) 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)

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 scoring: 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_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?) :)