# 7 — Chat steuert Dinge (`apps/overlay-server` + `apps/overlay-web`)

**Wirkrichtung:** Bindung. Aus Zuschauen wird Mitmachen.

## Aufbau

```
Chat-Command ──► overlay-server (4791) ──► WS ──► Browser-Source in OBS
                        │
                        ├──► obs-websocket   (Szenen, Filter, Quellen, Hotkeys)
                        ├──► Home Assistant / WLED  (Licht)
                        └──► Helix            (Umfragen, Titel)
```

`overlay-server` ist ein Fastify-Server, der drei Dinge tut: Overlay-Seiten
ausliefern, den WS-Kanal zu den Browser-Sources halten, und Commands vom
Event-Bus in Aktionen übersetzen.

## Overlay-Seiten (Browser-Sources in OBS)

| Pfad | Zweck | Größe |
|---|---|---|
| `/overlay/alerts` | Follow/Sub/Raid-Einblendungen | 1920x1080 |
| `/overlay/effects` | Emote-Regen, Soundboard-Feedback, Konfetti | 1920x1080 |
| `/overlay/community` | Chatter-Hinweis (nur für Abdu) | 480x220 |
| `/overlay/poll` | laufende Umfrage | 480x600 |
| `/overlay/game` | Minigame-Anzeige | 1920x1080 |
| `/overlay/raid-panel` | Raid-Ziele am Streamende | 900x600 |

Alle Seiten teilen sich einen WS-Client (`packages/shared/overlay-client.ts`)
mit automatischem Reconnect — eine Browser-Source, die nach einem Serverneustart
tot bleibt, ist der häufigste Fehler bei solchen Overlays.

## Command-Registry

Commands liegen deklarativ in `config/commands.yaml`:

```yaml
- trigger: "!sound"
  args: [name]
  cooldown: { global: 20, user: 120 }
  permission: everyone
  cost: 50            # Punkte, optional
  action: { type: sound, file: "sounds/{name}.mp3" }

- trigger: "!licht"
  args: [farbe]
  cooldown: { global: 60 }
  permission: subscriber
  action: { type: wled, preset: "{farbe}" }
```

Aktionstypen: `sound`, `overlay-effect`, `obs-hotkey`, `obs-source-toggle`,
`obs-filter`, `wled`, `helix-poll`, `set-title`, `script`.

**Cooldowns und Rechte sind nicht optional.** Ein Soundboard ohne Cooldown ist
nach zwei Streams abgeschaltet. Default: 20 s global, 120 s pro User,
Sounds nur für Follower.

## Minispiele

Ausbaustufe 2. Kandidaten, die bei kleinem Chat funktionieren (wichtig: sie
dürfen mit 3 Mitspielern genauso gut sein wie mit 30):

- **Tipprunde** — `!tipp <zahl>`, Abdu löst auf, Punkte für die Nächsten
- **Kollektive Entscheidung** — Helix-Umfrage mit echter Konsequenz im Spiel
- **Boss-Bingo** — Karte im Overlay, Chat ruft Felder aus

## Umfragen mit Konsequenz

`!umfrage` startet eine Helix-Poll (`POST /helix/polls`). Bei `poll.end` führt
der Server die hinterlegte Aktion zur Gewinneroption aus — Szenenwechsel,
Schwierigkeitsgrad, nächstes Spiel. Der Unterschied zu einer normalen Umfrage
ist, dass das Ergebnis automatisch etwas tut, statt nur angezeigt zu werden.

## Sicherheit

Alles, was den Stream sichtbar verändert oder Geräte im Haus schaltet, ist
missbrauchbar. Deshalb:

- `overlay-server` bindet nur auf `127.0.0.1`.
- Der Panik-Command `!aus` (Mods) schaltet alle Effekte für 10 min ab.
- Aktionen mit `requires_approval: true` erscheinen erst in einer Warteschlange
  im Overlay-Panel und laufen nach Abdus Klick.
- Kein Command darf beliebigen Text auf dem Bildschirm anzeigen. TTS und freie
  Textanzeigen sind bewusst nicht Teil von Ausbaustufe 1.

## Abnahmekriterien

- `!sound huch` spielt innerhalb von 300 ms den Sound ab.
- Cooldown greift und wird im Chat sichtbar quittiert (einmal, nicht bei jedem
  Versuch).
- OBS-Neustart oder Server-Neustart: Browser-Source verbindet sich innerhalb von
  5 s automatisch neu.
- `!aus` stoppt sofort alle laufenden Effekte.