5.2 Lamps

Controlled lamps are used to highlight shots on the playfield and to keep track of the progress of scoring features. Unlike general illumination, each lamp is individually controllable by the CPU.

Lamps are numbered from 0 to NUM_LAMPS-1. For each lamp, there are several flags that can be set to determine its physical state. The job of the lamp driver is to combine all of these flags into a single output value, and send that to the underlying hardware.

Every lamp has a basic state, which is either on, off, or flashing. The basic state of a lamp is a per-player value and is automatically saved and restored as players change in a multiplayer game. It is managed by the following APIs:

lamp_on

Turns on a lamp.

lamp_off

Turns off a lamp.

lamp_test

Tests whether a lamp is on/off.

lamp_toggle

Toggles a lamp's on/off state.

lamp_flash_on

Enable lamp flashing. Note that the steady state of a lamp must be off in order for the flashing to be seen. (I.e., if you call lamp_on(), and then lamp_flash_on(), the lamp will be steady.)

lamp_flash_off

Disable lamp flashing.

lamp_flash_toggle

Toggle lamp flashing.

lamp_tristate_on

Ensure the lamp is steady.

lamp_tristate_off

Ensure the lamp is off.

lamp_tristate_flash

Ensure the lamp is flashing.

The basic state may be temporarily overriden via a lamp effect. An effect can allocate a lamp, thereby overriding its basic value. When the effect finishes, it frees the lamp, causing the basic state to be shown again (see Lamp Effects).

In the machine description, you can attach a color and coordinates to each lamp. These are not used by the core OS, but they can be used to construct nice looking lamp effects that manipulate them in certain patterns.