achievement_groups:

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_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.)

##! mode: mode1
#! # create some empty achievements for the group
#! achievements:
#!   world_tour:
#!     enable_events: world_tour_fail, ball_will_end
#!   money_bags:
#!     enable_events: money_bags_fail, ball_will_end
#!   music_awards:
#!     enable_events: music_awards_fail, ball_will_end
#!   jukebox:
#!     enable_events: jukebox_fail, ball_will_end
#!   play_poker:
#!     enable_events: play_poker_fail, ball_will_end
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:

Required settings

The following sections are required in the achievement_groups: section of your config:

achievements:

List of one (or more) values, each is a type: string name of a achievements: device. Defaults to empty.

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.

Optional settings

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

allow_selection_change_while_disabled:

Single value, type: boolean (true/false). Default: 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:

Single value, type: boolean (true/false). Default: 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_events:

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

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.

disable_random:

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

Help us write it!

This section is unwritten or needs an update or edit. Can you help write it? Get your name in lights and geeky pinball bragging rights! Hit the magic sparkly wand to the right of the title to see this page source on GitHub. Then add/edit and submit your change. It's easy!

CLICK TO LEARN HOW TO EDIT THIS PAGE

disable_while_achievement_started:

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

If True, this achievement 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_events:

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

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.

enable_while_no_achievement_started:

Single value, type: boolean (true/false). Default: 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.

events_when_all_completed:

List of one (or more) events. Those will be posted by the device. Defaults to empty.

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_enabled:

List of one (or more) events. Those will be posted by the device. Defaults to empty.

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

events_when_no_more_enabled:

List of one (or more) events. Those will be posted by the device. Defaults to empty.

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.

rotate_left_events:

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

Default: None

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

rotate_right_events:

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

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.

select_random_achievement_events:

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

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.

show_tokens:

One or more sub-entries. Each in the format of string : string

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.

show_when_enabled:

Single value, type: string name of a shows: device. Defaults to empty.

Name of the show that will be started when this achievement group has been enabled. Also, any tokens configured in the show_tokens: section will be passed to the show here.

start_selected_events:

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

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.

sync_ms:

Single value, type: integer. Defaults to empty.

Help us write it!

This section is unwritten or needs an update or edit. Can you help write it? Get your name in lights and geeky pinball bragging rights! Hit the magic sparkly wand to the right of the title to see this page source on GitHub. Then add/edit and submit your change. It's easy!

CLICK TO LEARN HOW TO EDIT THIS PAGE

console_log:

Single value, type: one of the following options: none, basic, full. Default: basic

Log level for the console log for this device.

debug:

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

Set this to true to see additional debug output. This might impact the performance of MPF.

file_log:

Single value, type: one of the following options: none, basic, full. Default: basic

Log level for the file log for this device.

label:

Single value, type: string. Default: %

Name of this device in service mode.

tags:

List of one (or more) values, each is a type: string. Defaults to empty.

Not used

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

achievement_groups:

Required settings

achievements:

Optional settings

allow_selection_change_while_disabled:

auto_select:

disable_events:

disable_random:

disable_while_achievement_started:

enable_events:

enable_while_no_achievement_started:

events_when_all_completed:

events_when_enabled:

events_when_no_more_enabled:

rotate_left_events:

rotate_right_events:

select_random_achievement_events:

show_tokens:

show_when_enabled:

start_selected_events:

sync_ms:

console_log:

debug:

file_log:

label:

tags:

Related How To guides