Skip to content

Light State Controller

The Light State Controller is a VPX scripting class developed by flux5009 (mpcarr) for managing complex light behaviors in original (non-ROM) tables. It solves problems that Lampz alone cannot handle: RGB insert lights with multiple simultaneous flashing states, custom sequences on light banks, and spatial effects.

GitHub: https://github.com/mpcarr/vpx-light-controller

Architecture

The controller stores multiple light states per light, then on each FrameTimer tick generates an array of current states to display. A single light can have multiple states stacked on it -- the controller cycles between them. For example, a shot light can be simultaneously solid green (available) and flashing red (hurry-up), with the controller managing priority and transitions.

Key Design Decisions

  • Standalone system -- v0.9+ removed Lampz dependency entirely. For original tables, this eliminates the need for Lampz while providing fading, callbacks, and lightmap sync.
  • ROM-based tables should still use Lampz/vpmMapLights for standard lamp driving. The Light Controller is designed for original tables.
  • FrameTimer driven -- the LampTimer must be enabled in VPX for the controller to process any light state changes.

Core Features

Multi-State Light Cycling

A single light can have multiple states stacked on it. The controller cycles between them, enabling effects like simultaneous solid and flashing states with different colors.

Color Palette Support (v0.9+)

Color palettes (originally from the Die Hard table) allow pre-defined color sets. The controller can fade between colors over a specified timeframe, calculating intermediate colors during the transition.

Synchronized blinking across groups of lights:

AddLightToBlinkGroup GroupName, Light
RemoveLightFromBlinkGroup GroupName, Light
UpdateBlinkGroupPattern GroupName, pattern
UpdateBlinkGroupInterval GroupName, interval
StartBlinkGroup GroupName
StopBlinkGroup GroupName

Set up groups once, then start/stop as needed during gameplay. Works with existing sequences and pulse commands.

Lightmap Color Sync

Changing a light's color via the controller automatically syncs the color to attached lightmaps. Requirements: - The lightmap primitive name must include the light name (e.g., _l01_ in the lightmap name for light l01), OR - Put the light name in the light's UserValue property

This enables RGB color changes on toolkit-baked inserts.

Panlandia -- Coordinate-Based Sequences

A coordinate-based sequence system that uses light positions on the playfield to create spatial effects: sweeps, waves, falling blocks. Effects can be created in 5-10 minutes. Works by mapping light XY coordinates and triggering groups based on geometric patterns.

Interval-Based Light Mapping

When lights are mapped with interval numbers (TimerInterval property), turning on a light via the controller also turns on all other lights with the same interval number. Lights sharing an interval number are treated as a group.

Setup Requirements

  1. Include the Light Controller class in your table script
  2. Initialize the controller during Table_Init
  3. Enable the LampTimer in VPX -- this is the most common setup mistake. Without it, no light state changes process.
  4. When ending attract mode, call lightCtrl.StopSyncWithVpxLights() to stop attract patterns from overriding game-controlled light states

Integration Notes

  • The controller is designed for original tables where you have full control over light behavior
  • For ROM-based tables, standard Lampz/vpmMapLights remains the correct approach
  • The controller works alongside the VPX 10.8+ light_animate system for toolkit insert control
  • Video file animation maps (e.g., from After Effects) are identified as a future addition but not yet supported