achievements:¶
Config file section
Valid in machine config files | NO |
Valid in 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
##! 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.
events_when_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 this achievement is complete.
events_when_disabled:¶
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 is disabled.
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 is enabled.
events_when_selected:¶
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 is selected.
events_when_started:¶
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 is started.
events_when_stopped:¶
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 is stopped.
reset_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 reset back to its
default state (which will either be “disabled” or, if you have
start_enabled: true
, “enabled”)
restart_after_stop_possible:¶
Single value, type: boolean
(true
/false
). Default: true
Is it possible to restart this achievement after it’s been stopped?
restart_on_next_ball_when_started:¶
Single value, type: boolean
(true
/false
). Default: false
If True/Yes, then this achievement will stay in the “started” state when the player’s next ball starts if it was in the “started” state when the previous ball ended. This is useful if you want to restart a mode that was running when the ball ended.
Note that this restart will also play the show_when_started:
show, and it
will also post the events_when_started:
events.
If False/No, this achievement’s state will change from “started” to “stopped”
when the next ball starts. This will not play the show_when_stopped:
show and
it will not post the events_when_stopped:
events.
select_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’s selected property to ‘true’. These events will also cause the achievement to play the
show defined in the show_when_selected:
setting and to emit (post) events
in the events_when_selected:
setting.
Note that “selected” property, in MPF, is used to describe an achievement
that is currently selected (“highlighted” or “lit”) and available to be
started. This would typically be tied to a show (via the
show_when_selected:
setting) that causes a light or LED to flash.
Also, note that more than one achivement may be selected at a time; see unselect_events:
to change the selected property to false.
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. (See the settings called “show_when_XXX” further down in this documentation.)
show_when_completed:¶
Single value, type: string name of a shows device. Defaults to empty.
Name of the show that will be started when this achievement has been completed.
show_when_disabled:¶
Single value, type: string name of a shows device. Defaults to empty.
Name of the show that will be started when this achievement has been disabled.
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 has been enabled.
show_when_selected:¶
Single value, type: string name of a shows device. Defaults to empty.
Name of the show that will be started when this achievement has been selected.
show_when_started:¶
Single value, type: string name of a shows device. Defaults to empty.
Name of the show that will be started when this achievement has been started.
show_when_stopped:¶
Single value, type: string name of a shows device. Defaults to empty.
Name of the show that will be started when this achievement has been stopped.
start_enabled:¶
Single value, type: boolean
(true
/false
). Defaults to empty.
Whether this achievment is enabled or disabled when it is first loaded.
start_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 this achievement to switch to its
“started” state. These events will also cause the achievement to play the
show defined in the show_when_started:
setting and to emit (post) events
in the events_when_started:
setting.
stop_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 this achievement to switch to its
“stopped” state. These events will also cause the achievement to play the
show defined in the show_when_stopped:
setting and to emit (post) events
in the events_when_stopped:
setting.
sync_ms:¶
Single value, type: integer
. Defaults to empty.
A sync_ms value used for any shows which are started by this achievement. See the full sync_ms documentation for details.
unselect_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’s ‘selected’ property to become false.
console_log:¶
Single value, type: one of the following options: none, basic, full. Default: basic
Log level for the console log for this device.
file_log:¶
Single value, type: one of the following options: none, basic, full. Default: basic
Log level for the file log for this device.