Note

Please participate in the MPF User Survey 2018.

counters:

Config file section

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

See also counters.

Settings

The structure of counter logic blocks is like this:

 
counters:
   the_name_of_this_counter:
      count_events: my_count_event
      count_complete_value: 10
   some_other_counter:
      count_events: s_my_switch_active
      starting_count: 50
      count_interval: 10
      count_complete_value: 100

Note that the actual name of the counter doesn’t really matter. Mainly it’s used in the logs and for event names.

count_events:

This is an event (or a list of events) that, when posted, will increment or decrement the count for this Counter.

Note that if you include multiple events in this list, any one of the events being posted will cause the hit count to increase. If you want to track different kinds of events separately, use an Accrual or Sequence Logic Block instead.

This setting is required.

count_complete_value:

When the Counter exceeds (or gets below if you’re counting down) this value, it will post its “complete” event and be considered complete.

Default is None.

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

multiple_hit_window:

This is an MPF time value string that will be used to group together multiple count_events as if they were one single event. So if you have multiple_hit_window: 500ms and you get three hit events 100ms apart, they will all count as one hit.

Note that subsequent hits that come in during the time window do not extend the time. So with the 500ms hit_window from above, the first hit counts and sets the timer, another hit 300ms later won’t count, but a third hit 300ms after the second (and 600ms after the initial hit) will count (and it will set its own 500ms timer to ignore future hits).

Default is 0 (which means all hits are counted).

count_interval:

Specifies the numeric count change is for each hit. In other words, this is how much is added or removed from the count with each hit. Default is 1, but you can make it whatever you want if you want your count to increase by more or less than one whenever a count event occurs. You could use this, for example, in a mode to create a counter that tracks the value of a shot. Maybe it starts at 2,000,000, but each shot a playfield standup increases the value by 250,000.

Default is 1.

direction:

This is either up or down and specifies whether this counter counts up or counts down.

Default is up.

starting_count:

This is the starting value of the Counter and the value it goes back to when it’s reset. Default is zero. If you’re configuring a counter with direction: down, you’ll want to also set this to something more than zero.

Default is 0.

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

player_variable:

By default, the current “state” (or progress) of logic blocks is stored in a player variable called <counter_name>_state. For example, a logic block called “logic_block_1” would store its state in a player variable called logic_block_1_state.

However, you can use the player_variable: setting to change this to any player variable you want. Making this change doesn’t really affect anything other than the name of the variable. It’s just for convenience if you prefer a different name.

Note that this player variable stores the state the logic block as a numerical value: current count value for counters, steps accrued for accruals, and current step number for sequences. In other words, when a logic block is just started or reset, the player variable tracking it is set to 0. Then that increases by one as each step/count is complete.

You can easily use this numerical value in a text widget to show the number of combos complete, or the number of pop bumper hits required for super jets, etc. This player variable “state” is different than the state of the logic block itself, which is an object with enabled, completed, and value attributes. Note the difference in accessing the logic block state as a dynamic value vs. placeholder text:

variable_player:
  counter_hit:
    score: 100 * device.counters.logic_block_1.value
                 # The logic block stores the count as the 'value' attribute

widgets:
  counter_widget:
    - type: text
      text: (logic_block_1_state) Hits!
            # The player variable is the count value itself

Note

The player variable is only saved if the logic block is configured with persist_state: True. If persist_state is False, the logic block value will _not_ be saved under any variable name (not even the default).

persist_state:

Boolean setting (yes/no or true/false) which controls whether this logic block remembers where it was from ball-to-ball. If False, then this logic block will reset itself whenever a new ball starts. If True, then this logic block will be saved to the player variable <logic_block_name>_state.

Note that logic block state is always maintained on a per-player basis, regardless of what this setting is configured for.

Default is False.

reset_on_complete:

True/False (or Yes/No) which controls whether this logic block resets itself once it completes. This just resets the current value or progress. It does not change the enabled or disabled state.

Default is True.

disable_on_complete:

True/False (or Yes/No) which controls whether this logic block disables itself once it completes. This does not reset the current value.

Default is True.

Events posted by this logic block

You can enter a list of one (or more) events that will be posted when certain things happen to this logic block. Enter multiple events in MPF list format.

events_when_hit:

Event(s) posted when this logic block is “hit”, meaning that one of the sequence events, accrual events, or count events was just posted and advanced this logic block’s state.

Note that the event logicblock_(name)_hit will always be posted, regardless of whether you have anything set here.

events_when_complete:

List of one (or more) events which, when posted, will

Note that the event logicblock_(name)_complete will always be posted, regardless of whether you have anything set here.

Control Events

The following settings are used to configure events that will change the state of this logic block. Note that each of these can be one or more events.

You can list multiple events in the events list format which means you can specify delay times where the logic block will delay its enabling until the time passes.

enable_events:

Event(s) that will enable this logic block.

A logic block must be enabled to track hits, progress, and to post events.

If you don’t have any enable_events listed, then the logic block will automatically be enabled when the player’s ball starts.

Default is None.

disable_events:

Event(s) that will disable this logic block.

A logic block must be enabled to track hits, progress, and to post events.

Default is None.

reset_events:

Event(s) that will reset this logic block back to its original value. This has no effect on the enabled/disabled state of the block.

Note that there are also reset_on_complete: and persist_state: settings which also affect how and when the logic block is reset.

You can reset a logic block regardless of whether it’s enabled.

Default is None.

restart_events:

List of one (or more) events which, when posted, will restart this logic block. A restart is a reset, then an enable, combined into a single action.

Default is None.