# Controls and effects

## Matrix editing

| Control | Behavior |
|---|---|
| Manual | Stored RGB/brightness values only. |
| External | Final background + reactive composition, or another connected CHOP source. |
| Add | Clamped sum of manual and external **channels**, including brightness. This is not the effect layer's alpha blend. |
| Apply Cell / Fill All | Copy editor values into one/all manual cells. |
| Clear Manual | Zero manual values; does not disable external effects. |
| Paint | Presses apply the editor values as well as triggering reactive input. |
| Small-button Off / On / Blink | Edit the selected small LED's manual state. Use Manual or Add to see it. All On/All Off affect the 16 small LEDs only. |
| Physical faders | Read-only virtual monitoring. No lighting assignment. |

Choosing a background or reactive preset selects External automatically. Changing one layer preserves the other. **No background** stops only the generated background; saved colors may remain underneath. Reactive **Off** disables that layer and clears its event history.

## Continuous backgrounds

| UI name | Behavior |
|---|---|
| No background | No generated effect; stored colors can still show via Saved pad colors underneath. |
| Rainbow | Moving spatial hue gradient. |
| Center ripple | Continuous outward rings around `(3.5,3.5)`, between the four middle pads, with cycling hue. Ignores press origins. |
| Cycle | Uniform color cycling across the board. |
| Chase | One moving light through the 80 logical positions. |
| Breathe | Smooth intensity pulse; built-in blue color before any advanced color override. |
| Sparkle | Time-stepped pseudo-random sparse lights. |
| Trails | Moving chase head with a fading tail. In the final background layer it receives no press events. |
| IMAGE / TOP | Incoming TOP downsampled to 8×8; reactive effects can overlay it. |

The former RGB-steps preset was removed. These backgrounds run continuously, independent of Hold.

## Reactive layer

| UI name | Behavior |
|---|---|
| Off | No reactive overlay. |
| Ripple | Outward ring centered on the pressed pad or small-button position. Hue follows a running cycle and radial distance, so held repeats do not restart at red. |
| Flash | Whole-surface white flash on press; sustained while held when Hold is enabled. |

Multiple pressed origins can coexist. Overlapping ripples use the strongest ring at each cell, not additive color accumulation. **Repeat while held** emits new rings at the repeat interval; release stops new rings and existing rings finish fading. **One ripple per press** disables repeats. Shift is mapped to logical position 79, the bottom-right side-button position; it is not a modifier and has no LED.

## Effect settings / custom parameters

These controls live on `lighting_effects`; code names are case-sensitive. Ranges below are the final settings slider ranges, not a guarantee that every older custom parameter definition uses the same minimum.

| UI label | Parameter | Range | Meaning |
|---|---|---|---|
| Background speed | `Speed` | 0.05–4 | Generated background motion; does not retime TOP media. |
| Background intensity | `Level` | 0–1 | Generated effect strength or media brightness multiplier. |
| Reactive speed | `Reactivespeed` | 0.05–4 | Ripple travel and hue cycle; Flash decay speed. |
| Reactive intensity | `Reactivelevel` | 0–1 | Reactive alpha/strength over the background. |
| Ring width | `Width` | 0.1–4 | Thickness in cell units; affects both ripple types. |
| Pressed ripple fade | `Fade` | 0.2–30 s | Maximum life/fade of a pressed ring. Does not time the continuous center effect. |
| Hold repeat interval | `Repeat` | 0.1–3 s | Time between repeated held rings; independent of travel speed. |
| Saved pad colors underneath | `Background` | 0–1 | Manual color layer beneath generated backgrounds; not used beneath media. |
| Repeat / one press | `Hold` | toggle | Reactive hold behavior. |
| Background choice | `Preset` | menu | One background, including `media`. |
| Reactive choice | `Reaction` | menu | `off`, `ripple`, or `flash`. |

Advanced parameters retained from earlier versions: `Colors` (`preset`, `assigned`, `single`) and `Fxred/Fxgreen/Fxblue` affect generated background colors. Center ripple always uses its own cycling hues. Media bypasses these overrides. The current reactive layer uses its own RGB/white colors. These advanced color controls are hidden in the simplified settings window.

Other important parameters:

- `matrix`: `Mode`, `Row`, `Col`, `Red`, `Green`, `Blue`, `Brightness`; pulses `Apply`, `Fill`, `Clear`, `Load`, `Preview`.
- `controller_ui.Paint`: apply the editor color on pad presses.
- `small_button_lights.Selected`: small-LED index 0–15.
- `media_input.Level`: additional alpha/brightness scaling, 0–1.
- `apc_mini_mk2_adapter`: `Devicename`, `Enabled`, `Status`, `Sent`, `Received`, `Lastinput`. Use Connect APC/MIDI Off instead of changing Enabled alone, because the actions also configure operators and cached state.

Settings opens through `effect_settings_window`, centered on the primary display with a title bar. The main controller viewer still uses TD's floating viewer behavior.