# Milionář — refactor and cleanup plan

**Scope amendment, 2026-10-12:** Standa approved the second mode **Příběh**. Preserve its small engine and the shared modern launch/dialog/provider/voice boundaries described in `../story-game/000-index.md`. “One game” below describes the earlier legacy cleanup scope, not authorization to delete Story. Coordinate shared-file moves with the Story handoff; retain compatible public entry/Subject exports.

Goal: one game (Milionář), one window (the modern card, `games/DialogMilionarGameModern.xml`), one entry point, clean
modular code. **Behaviour and looks of the modern game stay exactly as they are now** (they are the required state).

## Decisions (Standa, 2026-10-08)

| Topic | Decision |
|---|---|
| Other games | Quiz and text adventure are removed completely (code, AI functions, XML, strings). |
| Windows | Only the modern card; classic card, `milionar_game_design` setting, inline panels go. |
| Notification at video start | "Hrát hru" opens the modern game modal **over the running video** (no pause). The inline game panel of the notification is removed. |
| Plugin action | `play_text_game` is **renamed** to `milionar_game`; no alias (old saved links stop working). |
| LLM calls of the game | Move from `wcs/ai/AIHandler.py` into the game package (coordinate with the AI-provider session that edits `wcs/ai`). |
| Process | Phases; each verified with the game harness + Kodi screenshots, then Standa tests; no commit unless asked. |

## Current state (what exists today)

Three generations of game code live side by side:

1. **Legacy games** — `GameManager.py` (game selection), `QuizGame.py`, `AdventureGame.py`, `DialogWcsTextGame.py`
   (`TextGameWindow`, no longer instantiated; only its XML name is still passed around), `games/DialogWcsTextGame.xml`,
   `playback/dialogs/base_game_dialog.py` (inline game in the video-start notification) + game panels in
   `notifications/{classic,modern,premium}/Dialog{Movie,Episode}InfoWithGame.xml` and `DialogAutoplayCountdown.xml`,
   ~600 lines of quiz / text-game functions in `wcs/ai/AIHandler.py` (actor/director/creator/writer variants).
2. **Classic card** — `games/DialogMilionarGame.xml`, `designs.CLASSIC` + setting `milionar_game_design`, the inline
   MyTV panel (`DialogMyTV_appletv.xml`, control 9514, `MillionaireMyTVAdapter` classic properties),
   `DialogShowCorrectAnswer` + setting `millionaire_show_correct_answer`, `millionaire_highlight_delay`,
   `text_formatter.py`, and ~60 % of `MillionaireGame.py` (2122 lines) that builds display texts, sidebar items and
   ladder colours for the classic UI.
3. **Modern card** (kept) — `DialogMilionarGame.MilionarGameModal`, `game_view.py`, generated XML
   (`scripts/game_dialog/gen_modern_game.py`), content sources (`content/ai.py`, `content/demo.py`, demo pack),
   prompts, moderator styles, TTS/voice.

Entry points (each builds the game itself today): router `play_text_game`, `milionar_demo`, details / actor / director /
creator / search / My list dialogs, MyTV + MyCinema + Add media, library clicks / menu, skin actions / context /
detail / library_actions, video-start notification.

## Target structure

```
wcs/games/millionaire/
  __init__.py      open_game(subject, content=None)  — the only way to start a game (modal)
  subject.py       Subject: what the game is about (title, media type, plot, genre, episode, person, art, year)
  engine.py        game state machine: rounds, answers, prefetch, autoplay; no UI texts, no Kodi windows
  lifelines.py     50:50, audience poll (numbers + animation steps), tip
  view.py          view model -> WCS.Game.* properties (today game_view.py)
  dialog.py        MilionarGameModal (modern only) + the property bridge (slim MillionaireMyTVAdapter)
  content/         ai.py (continuous chat), demo.py ; demo/ (catalog, moderator, launch)
  llm.py           the game's LLM calls (chat, tip) — moved from wcs/ai/AIHandler.py
  prompts.py       + styles/*.md (moderator styles)
  voice.py, tts.py
```

Rules: one responsibility per module; the engine knows nothing about XML/properties; the dialog knows nothing about
game rules; content sources stay the seam between AI and demo; no duplicated "build the modal" code anywhere.

## Phases

### 0 — Safety net (no behaviour change)
- Golden runs: scripted demo games through the harness (win, loss at N, all lifelines, back/exit confirm, play again,
  autoplay) recording the full `WCS.Game.*` property sequence per step → `tests/golden/millionaire/*.json` + a test
  that replays and compares.
- Golden frames: live screenshots of every screen (title, rules, intro, question, tip, poll, countdown, feedback,
  long-text feedback, game over, win, results, error, exit confirm) → pixel compare after each phase.

### 1 — One entry point, all callers redirected
- `open_game(subject)`; plugin action `milionar_game` (replaces `play_text_game` in router, skin, library, context,
  dialogs, XML onclicks); every caller builds a `Subject` and calls it.
- Video-start notification: "Hrát hru" closes the inline panel logic and opens the modal over the running video.
- MyTV (all designs) / MyCinema / Add media open the modal (inline panel removed).

### 2 — Delete the legacy and the classic card
- Files: `GameManager.py`, `QuizGame.py`, `AdventureGame.py`, `DialogWcsTextGame.py`, `DialogShowCorrectAnswer.py`,
  `text_formatter.py`, `designs.py` (CLASSIC), `playback/dialogs/base_game_dialog.py`; XML `DialogWcsTextGame.xml`,
  `DialogMilionarGame.xml`, `DialogShowCorrectAnswer.xml`; game panels in the notification XMLs and the MyTV appletv
  inline panel.
- AIHandler quiz / text-game functions; settings `milionar_game_design`, `millionaire_show_correct_answer`,
  `millionaire_highlight_delay` + their strings (cs/sk/en); dead controller code (classic texts, sidebar, ladder colours,
  `get_continue_text`, `animate_generating_ladder`, legacy `current_level` / `current_choices`, …).

### 3 — Backend refactor
- Split `MillionaireGame.py` into `engine.py` + `lifelines.py`; move `llm.py`, `prompts.py`, styles, `tts.py`,
  `voice.py`, content, demo into the package; thread/timer handling in one place (workers, cancellation on close).

### 4 — Frontend refactor
- `dialog.py`: modal + bridge only for the modern card (no classic property set), focus handling in one place;
  generator `gen_modern_game.py` stays the single source of the XML (paths updated).

### 5 — Tests, harness, docs
- Tests updated to the package (`test_millionaire_*`), golden tests green, harness (`scripts/game_harness`,
  `wcs/devtools/game_probe.py`) on the new modules, `docs/features/009-milionar-game.md` + skills (`game-harness`,
  `app-prompts`, `kodi-ui`) updated, release build check (`build_zip.sh`) passes.

## Done means (each phase)
Golden property runs identical, golden frames pixel-identical (except intended removals), unit tests + harness
selftest + one live AI game green, `xmllint` clean, release ZIP builds, then Standa's numbered test checklist.