Skip to content

light_player: Config Reference

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 YES ✅
mode config files YES ✅

Note

This section can also be used in a show file in the lights: section of a step.

The light_player: section of your config is where you can control lights in config or shows. Example in config:

light_player:
  some_event:
    led1:
      color: red
      fade: 200ms
    led2:
      color: ff0000
      fade: 2000ms

shows:
  rainbow:
    - duration: 1s
      lights:
        (leds): red
    - duration: 1s
      lights:
        (leds): orange
    - duration: 1s
      lights:
        (leds): yellow
    - duration: 1s
      lights:
        (leds): green
    - duration: 1s
      lights:
        (leds): blue
    - duration: 1s
      lights:
        (leds): purple

Optional settings

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

color:

Single value, type: string. Default: white

Set a color to this light. Color values may be a hex string (e.g. 22FFCC), a hex string including a brightness value (e.g. 22FFCC%60), a color name (e.g. turquoise), or a brightness value (i.e. AA or 120). Note that a list of RGB values (e.g. [50, 128, 206]) cannot be used, these RGB values are only valid in the named_colors: section of your config file. MPF knows 140+ standard web color names, and you can define your own custom colors in the named_colors: section of your config. The colors MPF knows can be easily checked by reading: https://github.com/missionpinball/mpf/blob/dev/mpf/core/rgb_color.py If you use brightness on an RGB light MPF will use the brightness for every channel. For instance brigness AA will result in color AAAAAA.

Special color directives: on, off, and stop

MPF supports a few special terms that may be used instead of a color value.

on

If your light has a default_on_color set, then instead of having to name that color in particular, you can just use on. If you do not have one set, the light will instead turn white (or its native color if single-channel.)

off

When you turn a light on to a certain color in a show, it will remain on throughout the show unless directed otherwise. If you want your light to turn on for only a specific time, you will need to explicitly set it to off. Another use case for off is when a lower-priority show has a light turned on, but another show at a higher prority wants to override this -- you can set a light to off in a show without having turned it on in that show first, just to ensure it is truly off.

stop

The offdirective tells the light controller to specifically hold a light to no power, but does not release the light from control. If you instead have a show that no longer needs control over a light that it has already set at least once, you can use stop to remove the show's priority level hold on the light's color. Imagine having something like a lightning strike show, where lights from all over your machine flash yellow, but then immediately return to their previous color setting -- you would use stop the step after each light flash to allow the previously-set color to show through again.

fade:

Single value, type: ms_or_token. Defaults to empty.

Time to fade this light in ms. Use this to achieve smooth transitions between colors.

priority:

Single value, type: int_or_token. Default: 0

Relative priority of this entry in the light stack.

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