timers:

Config file section

Valid in machine config files NO
Valid in mode config files YES
Related Tutorial
Timers

The timers: section of your config is where configure timers that can “tick” up or down. Timers post events with each tick which you can use to update slides, etc. You can set the start and stop values of the timers, as well as how fast they tick, how much they change per tick, and other settings.

The settings structure of timers is like this:

timers:
   timer_name:
      <settings>
   some_other_timer_with_a_different_name:
      <settings>
   a_third_timer:
      <settings>

Here’s an example timers: section from the “Money Bags” mode in Brooks ‘n Dunn which contains two timers:

##! mode: mode1
timers:
    mb_intro_timer:
        start_value: 3
        end_value: 0
        direction: down
        control_events:
            - action: start
              event: mode_money_bags_started
    money_bags_timer:
        start_value: 15
        end_value: 0
        direction: down
        tick_interval: 1.25s
        control_events:
            - action: start
              event: timer_mb_intro_timer_complete
            - action: add
              event: money_bags_advertise_flashing_hit
              value: 5
            - action: stop
              event: logicblock_money_bags_counter_complete
This example is tested to be valid MPF config. However, it is not integration tested.
##! mode: mode1
timers:
    mb_intro_timer:
        start_value: 3
        end_value: 0
        direction: down
        control_events:
            - action: start
              event: mode_money_bags_started
    money_bags_timer:
        start_value: 15
        end_value: 0
        direction: down
        tick_interval: 1.25s
        control_events:
            - action: start
              event: timer_mb_intro_timer_complete
            - action: add
              event: money_bags_advertise_flashing_hit
              value: 5
            - action: stop
              event: logicblock_money_bags_counter_complete

In the example above, an intro timer which runs for 3 seconds is started by the event mode_money_bags_started (which means this timer starts when the mode starts). A second timer (the “money_bags_timer”) starts when the intro timer is complete. It starts with a value of 15 and counts down to 0 (but at a count interval of 1.25 seconds so it’s a bit slower than real time. It will also get reset back to 15 each time a flashing shot is hit.

Here’s another example of timers from Demo Man’s skillshot mode:

##! mode: mode1
timers:
  mode_timer:
    start_value: 3
    end_value: 0
    direction: down
    tick_interval: 1s
    control_events:
    - event: balldevice_playfield_ball_enter
      action: start
    start_running: false
  target_rotator:
    start_running: true
    tick_interval: 1s
This example is tested to be valid MPF config. However, it is not integration tested.
##! mode: mode1
timers:
  mode_timer:
    start_value: 3
    end_value: 0
    direction: down
    tick_interval: 1s
    control_events:
    - event: balldevice_playfield_ball_enter
      action: start
    start_running: false
  target_rotator:
    start_running: true
    tick_interval: 1s

The skillshot mode starts when the ball is waiting to be plunged. The timer called “mode_timer” in the example above starts when the ball enters the playfield and runs for 3 seconds. If it runs all the way down, the skill shot mode will stop (meaning the player missed the skillshot).

A second timer doesn’t have any count values associated with it, rather it just “ticks” once a second. That tick event is used to rotate the lit skillshot.

See timer_control_events: for more details about all the actions available in a timer.

Optional settings

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

bcp:

Single value, type: boolean (Yes/No or True/False). Default: False

Controls whether the various timer events (count, start, stop, complete, etc.) are sent to the MPF-MC via BCP.

console_log:

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

Log level for the console log for this device.

control_events:

List of one (or more) values, each is a type: timer_control_events.

Timer control events is where you specify what happens to this timer when other events are posted. See timer_control_events: for more details.

debug:

Single value, type: boolean (Yes/No or True/False). Default: False

If true/yes, adds additional logging information to the verbose log for this timer.

direction:

Single value, type: string. Default: up

Controls which direction this timer runs in. Options are up or down.

end_value:

Single value, type: integer or template (Instructions for entering templates).

Specifies what the final value for this timer will be. When the timer value equals or exceeds this (for timers counting up), or when it equals or is lower than this (for timers counting down), the timer_<name>_complete event is posted and the timer is stopped. (If the restart_on_complete: setting is true, then the timer is also reset back to its start_value: and started again.)

Note that you can use a dynamic value for this setting.

file_log:

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

Log level for the file log for this device.

max_value:

Single value, type: integer.

The maximum value this timer can be. If you try to add value above this, the timer’s value will be reset to this value.

restart_on_complete:

Single value, type: boolean (Yes/No or True/False). Default: False

Controls what should happen when this timer completes. If you have restart_on_complete: true, then this timer will reset back to the start_value and start again after it completes.

start_running:

Single value, type: boolean (Yes/No or True/False). Default: False

Controls whether this timer starts running (“started”), or whether it needs to be started with one of the start control events.

start_value:

Single value, type: integer or template (Instructions for entering templates). Default: 0

The initial value of the timer.

Note that you can use a dynamic value for this setting.

tick_interval:

Single value, type: time string (secs) or template (Instructions for entering time strings and Instructions for entering templates). Default: 1s

A time value for how fast each tick is. The default is 1 second, but quite often “pinball time” is slower than real world time, and a countdown timer will actually tick a speed that’s slower than 1 second per tick. (So in that case, you might set tick_interval: 1.25s or something like that. You can also set this really short if you want a hurry up, maybe every 100ms removed 77,000 worth of points or something.

Also note that you can use dynamic values here if you want to do math or use settings to make this configurable.