achievements:

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

The achievements: section of your config is where you configure player-based "achievement" tracking.

Like most things in MPF configs, the highest-level entries in the achievements: section of your config are the names of the individual achievements, and then indented under each of those are the settings for that individual achievement.

Here's an example achievements section from Brooks & Dunn:

##! mode: mode1
achievements:
  world_tour:
    show_tokens:
      leds: l_world_tour
    show_when_selected: flash
    show_when_started: flash
    show_when_completed: on
    events_when_started: start_world_tour_mode
    restart_after_stop_possible: true
    events_when_completed: rotate_mission_rotator, light_mission_select
    complete_events: world_tour_success
    enable_events: world_tour_fail, ball_will_end
  money_bags:
    show_tokens:
      leds: l_money_bags
    show_when_selected: flash
    show_when_started: flash
    show_when_completed: on
    events_when_started: start_money_bags_mode
    restart_after_stop_possible: true
    events_when_completed: rotate_mission_rotator, light_mission_select
    complete_events: money_bags_success
    enable_events: money_bags_fail, ball_will_end
  music_awards:
    show_tokens:
      leds: l_music_awards
    show_when_selected: flash
    show_when_started: flash
    show_when_completed: on
    events_when_started: start_music_awards_mode
    restart_after_stop_possible: true
    complete_events: music_awards_success
    events_when_completed: rotate_mission_rotator, light_mission_select
    enable_events: music_awards_fail, ball_will_end
  jukebox:
    show_tokens:
      leds: l_jukebox_insert
    show_when_selected: flash
    show_when_started: flash
    show_when_completed: on
    events_when_started: start_jukebox_mode
    restart_after_stop_possible: true
    events_when_completed: rotate_mission_rotator, light_mission_select
    complete_events: jukebox_success
    enable_events: jukebox_fail, ball_will_end
  play_poker:
    show_tokens:
      leds: l_play_poker
    show_when_selected: flash
    show_when_started: flash
    show_when_completed: on
    events_when_started: start_play_poker_mode
    restart_after_stop_possible: true
    events_when_completed: rotate_mission_rotator, light_mission_select
    complete_events: play_poker_success
    enable_events: play_poker_fail, ball_will_end

More examples:

Shows

The show_when_xxx settings control which show is played when this achievement switches to a new state.

Note that whatever show was playing from the previous state will be stopped.

Also, any tokens configured in the show_tokens: section will be passed to the show here.

Events posted by achievements

You can configure achievements to post certain events when they change state.

Note that all achievements will by default post events in the form [achievement_(name)_state_(state) when they change state. The events listed below as events_when_xxx, if defined, will replace the default event.

Control Events

The following xxx_events settings specify which MPF events cause this achievement to move to a new state.

Optional settings

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

complete_events:

List of one (or more) device control events (Instructions for entering device control events). Defaults to empty.

Events in this list, when posted, cause this achievement to switch to its "completed" state. This must be in the "started" state in order to be moved to the "completed" state when these events post. These events will also cause the achievement to play the show defined in the show_when_completed: setting and to emit (post) events in the events_when_completed: setting.

disable_events:

List of one (or more) device control events (Instructions for entering device control events). Defaults to empty.

Events in this list, when posted, cause this achievement to switch to its "disabled" state. These events will also cause the achievement to play the show defined in the show_when_disabled: setting and to emit (post) events in the events_when_disabled: setting.

enable_events:

List of one (or more) device control events (Instructions for entering device control events). Defaults to empty.

Events in this list, when posted, cause this achievement to switch to its "enabled" state. These events will also cause the achievement to play the show defined in the show_when_enabled: setting and to emit (post) events in the events_when_enabled: setting.

enable_on_next_ball_when_enabled:

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

If True/Yes, this achievement will stay "enabled" when the next ball starts if it was enabled when the last ball ended. If False/No, this achivement will be changed to "disabled" when the next ball starts.

This is similar to the restart_on_next_ball_when_started: event from above, except it applies to the "enabled" state instead of the "started" state.

This setting will also play the show_when_enabled: show and post the events_when_enabled: events when re-enabling, but will not play or post anything when disabling.