achievement_groups:

Config file section

New in version 0.32.

Valid in machine config files NO
Valid in mode config files YES

The achievements_groups: section of your config is where you configure grouping of multiple player-based “achievement” tracking.

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

Here’s an example achievement_groups section from Brooks & Dunn. (This is related to the example in the achievements config documentation.)

achievement_groups:
  my_group:
    achievements: world_tour, money_bags, music_awards, jukebox, play_poker
    enable_events: enable_mission_selection
    start_selected_events: shot_lower_vuk_from_playfield_hit
    select_random_achievement_events: rotate_mission_rotator
    events_when_enabled: mission_rotator_ready
    rotate_right_events: sw_toggle
    show_tokens:
      leds:
        l_begin_round
    show_when_enabled: flash

More examples:

General Settings

achievements:

List of one (or more) values, each is a type: string. Default: None

This is a list of the achievements (from the achievements: section of your mode config) that make up this group. The order here defines the order individual achievements are rotated in via the rotate_right_events: and/or rotate_left_events: settings.

allow_selection_change_while_disabled:

New in version 0.33.

Boolean (yes/no or true/false) setting. Default is False.

Controls whether the currently selected achievement can be changed when the achievement group is disabled. If False/No, then the rotate and select random events will have no effect when the group is disabled.

auto_select:

New in version 0.32.3.

Boolean (yes/no or true/false) setting. Default is False.

If True, this achievement group will automatically ensure that one of its member achievements is always selected. The selected achievement will be chosen at random from all the achievements in the “enabled” states (and the “stopped” states if restart_after_stop_possible: is set to True).

disable_while_achievement_started:

New in version 0.32.3.

Boolean (yes/no or true/false) setting. Default is True.

If True, this achievement group will automatically disable itself when any of its member achievements are in the “started” states. This is the default behavior because an achievement group is typically used to select an achievement to run, and while an achievement is running, you usually want to disable the selection process for the next achievement.

enable_while_no_achievement_started:

New in version 0.32.3.

Boolean (yes/no or true/false) setting. Default is True.

If True, this achievement will automatically enable itself when none of its member achievements are in the “started” states. This is the default behavior because an achievement group is typically used to select an achievement to run, so when none are running, you want to enable the group so that the next achievement can be selected.

show_tokens:

One or more sub-entries, each in the format of type: str:str. Default: None

This is an indented list of key/value pairs for the show tokens that will be sent to the shows that are played when this achievement changes state.

Note that you can configure show_tokens: at the group level (here) or the individual achievement level. That’s done for convenience, and in practical use, you’d just configure the show tokens in one place.

Control Events

The following settings specify which MPF events cause the achievements in this group to move to a new state.

enable_events:

One or more sub-entries, either as a list of events, or key/value pairs of event names and delay times. See the Device Control Events documentation for details on how to enter settings here.

Default: None

Events in this list, when posted, will enable this achievement group. This will play the show_when_enabled: and will post events in the events_when_enabled: settings.

This will also check to see if all the member achievements are complete, it will check to see if there are no more enabled achievements, and it will update the selected achievement.

Starting the selected achievement only works if the group is enabled. In other words, if something has to be “lit” before an achievement can start, then that is done via the group’s “enable” functionality.

disable_events:

One or more sub-entries, either as a list of events, or key/value pairs of event names and delay times. See the Device Control Events documentation for details on how to enter settings here.

Default: None

Events in this list, when posted, disable this achievement group. These events will also cause the achievements to play the show defined in their show_when_disabled: setting and to emit (post) events in their events_when_disabled: settings.

start_selected_events:

One or more sub-entries, either as a list of events, or key/value pairs of event names and delay times. See the Device Control Events documentation for details on how to enter settings here.

Default: None

Events in this list, when posted, cause any achievements in this group that are in the “selected” state to switch to their “started” state. (Typically there would only be a single achievement in the group that’s “selected” at any time, but you could have more than one.)

These events only work if the achievement group is enabled.

When the individual achievements change from “selected” to “started”, they will play their show_when_started: shows and post their events_when_started: events.

select_random_achievement_events:

One or more sub-entries, either as a list of events, or key/value pairs of event names and delay times. See the Device Control Events documentation for details on how to enter settings here.

Default: None

Events in this list, when posted, will randomly pick one of the available achievements and change it to its “selected” state. This is useful when a game is starting and you want one of the available achievements to start in a selected state. (e.g. pick a random mission to be highlighted.)

Note that the allow_selection_change_while_disabled: controls whether these events will work when the achievement group is disabled.

The “available” achievements which could be chosen here include achievements that are one of the following:

  • enabled
  • selected
  • stopped (if the achievement’s restart_after_stop_possible: is true/yes

An example of this would be in Attack From Mars, where the next country is randomly chosen (selected) after you default the saucer for the previous country.

If there are no more available events to be selected, then the events in events_when_no_more_enabled: are posted.

Note that if you want to always select a certain achievement (instead of randomly picking one), then you can just set that particular achievement’s select_events: entry rather than using this random selecting setting.

rotate_right_events:

One or more sub-entries, either as a list of events, or key/value pairs of event names and delay times. (See the Device Control Events documentation for details on how to enter settings here.

Default: None

Causes the states of the available achievements in this group to be rotated to the right.

Note that the allow_selection_change_while_disabled: controls whether these events will work when the achievement group is disabled.

This is used to “switch” the current selected achievement. For example, many games have main achievements you need to complete to get to wizard mode. Completed achievements have a light that’s solid on, available (enabled) achievements have a light that’s off (since they’re not yet complete but available to be played), and the current selected achievement has a light that’s flashing (indicating that it’s the next one to be played).

Then when you hit a slingshot or pop bumper, the currently selected (flashing) achievement changes, but you only want to rotate with other achievements that are enabled (available but not yet complete).

So if this is the current state:

  • Mission 1: completed
  • Mission 2: selected
  • Mission 3: enabled
  • Mission 4: enabled
  • Mission 5: enabled

And then one of the rotate_right_events: is posted (like from a pop bumper hit), the new list would look like this:

  • Mission 1: completed
  • Mission 2: enabled
  • Mission 3: selected
  • Mission 4: enabled
  • Mission 5: enabled

Notice that the “selected” state moved from Mission 2 to Mission 3, and the completed state of Mission 1 did not change.

Even though these are called “rotate” events, what really happens is that when this rotation occurs, the previously selected achievement changes from “selected” to “enabled”, and the newly selected achievement changes from “enabled” to “selected”. Both achievements will stop their current shows and play the shows associated with their new states, and both will post the events associted with their new states.

Note that if you want to select a random achievement instead of the next one on the list, you can use a select_random_achievement_events: event instead.

rotate_left_events:

One or more sub-entries, either as a list of events, or key/value pairs of event names and delay times. (See the Device Control Events documentation for details on how to enter settings here.

Default: None

Same as rotate_right_events:, but it rotates the selected achievement in the opposite direction.

Events posted by achievements

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

Note that all achievements will always post events in the form achievement_(name)_state_(state) when they change state. The events listed below are in additional to that event.

events_when_enabled:

List of one (or more) values, each is a type: string. Default: None

A single event, or a list of events, that will be posted when this achievement group is enabled.

events_when_all_completed:

Changed in version 0.32.3.

Prior to MPF 0.32.3, this event was called “events_when_all_complete”. This was a mistake since the completed state is called “completed”, not “complete”

List of one (or more) values, each is a type: string. Default: None

A single event, or a list of events, that will be posted when all the achievements in this group are in the “completed” state. This is useful for posting events to start a wizard mode, for example.

events_when_no_more_enabled:

List of one (or more) values, each is a type: string. Default: None

A single event, or a list of events, that will be posted when one of the events in the select_random_achievement: is posted but there are no more available achievements to be selected.

Shows

The following 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.

show_when_enabled:

Single value, type: string. Default: None

Name of the show that will be started when this achievement group has been enabled.