# Cycle Effect, Tag Colour Library and Colour Editor

**Date:** 2026-04-06
**Project:** lego-dimensions-reader
**Status:** resolved
**Tags:** led-effects, cycle, tag-colors, tkinter, cli-client

## Context
Jess wanted a "revolving" light effect that chases around all three pads for certain characters, a themed colour entry for every character in the library, and a GUI to edit those colours. Adding the cycle effect exposed a removal bug: when a cycle tag was lifted, only its own pad cleared and the other two stayed frozen mid-cycle; and removing an unrelated tag could kill a running cycle.

## Key Decisions
- **Light only the pad the tag is on** for normal effects — earlier behaviour could affect other pads.
- **`software_cycle` effect** tracked under a special internal key (`99`) so it's managed separately from per-pad effects; supports a `trail` parameter for a dim afterglow on inactive pads.
- **Removal rules:**
  - Remove a cycle tag → stop the cycle, clear all three pads, then re-apply themes for any tags still present.
  - Remove a non-cycle tag while a cycle runs elsewhere → leave the LEDs alone.
  - Normal removal → turn off just that pad.
- **`builtin_led_effects` flag** lets external clients (the CLI client) disable the base reader's default LED behaviour so it doesn't override themes.
- **Softer RGB values** — full-brightness multi-channel colours look washed out on the portal (e.g. cyan `[0,255,255]` → `[0,180,160]`).
- **Dedicated Tag Colour Editor (tkinter)** rather than hand-editing JSON.

## Technical Details
- `tag_colors.json` — 82 themed tag mappings (colour, effect, speed, optional cycle/trail).
- `dimensions_cli_client.py` — CLI client that sends card IDs to Moonlight (`POST /api/video/play`, port 8547) and applies themed effects; supports cycle.
- `tag_color_editor.py` — GUI for editing `tag_colors.json`.

## Code Changes
- `lego_dimensions_reader.py` — per-pad lighting fix; `software_cycle` effect.
- `dimensions_cli_client.py` — cycle support; restore other pads on cycle removal; don't kill cycle on non-cycle removal.
- `tag_color_editor.py` — new.
- `tag_colors.json` — complete 82-entry set.
- `README.md` — cycle effect examples.

## Open Questions / Next Steps
- Separate idea: figures on a reader pad switching Zigbee smart plugs (Tuya gateway + `tinytuya` cloud mode). Hardware bought, not yet paired; needs Tuya IoT developer credentials (`<redacted>`) and plug names before a mapping module can be built.

## Artifacts
- `2b4ca64` — Restore other pads when cycle effect tag is removed
- `ac190d4` — Don't kill cycle effect when removing non-cycle tags
- `692c149` — Add software_cycle effect
- `c7dd1a6` — Add Tag Color Editor GUI tool
- `65512de` — Complete tag_colors.json with 82 themed tag mappings