# Архитектура проекта

Коллекция терминальных игр на Go (Bubble Tea + Lipgloss). Этот файл
описывает, как устроен код: что за что отвечает, где и как хранятся
сохранения, и — отдельным разделом — подробно разбирает экономику и
вероятности режима истории (сторимода), самой сложной части проекта.

Общий объём: ~27 000 строк кода, ~18 000 строк тестов, 17 игр.

## 1. Общая структура файлов

### Инфраструктура (общая для всех игр)

| Файл | За что отвечает |
|---|---|
| `main.go` | Точка входа — запуск программы Bubble Tea |
| `menu.go` | Главное меню: выбор языка, реестр игр (`gameRegistry`), все экраны настройки сложности/вариантов перед началом партии, диспетчеризация состояний верхнего уровня (`AppModel.Update`/`View`) |
| `tui.go` | Общие для всех игр стили (`lipgloss`), рендер карт (`renderCardBox`/`renderCardBoxHand`), `wrapText` (перенос длинного текста по ширине терминала), тип `ColorChoice` (общий выбор цвета/стороны для 2-игроцких игр) |
| `i18n.go` | Механизм переключения языка (`SetLanguage`/`CurrentLang`) |
| `translations.go` | Все строки интерфейса на русском и английском (один общий словарь `map[string][2]string`, доступ через `T(key)`/`Tf(key, args...)`) |
| `translations_wayfarer{1..4}.go` | То же самое, но переводы Странника вынесены в отдельные файлы — их одних около 900 строк текста квестов |
| `rules.go` | Тексты правил каждой игры (RU/EN), показываются по `--help`/`--help-en` и из меню |
| `banner.go` | ASCII-баннер главного меню и его компактная замена для низких терминалов |
| `card.go`, `deck.go` | Общий тип карты/масти/ранга и колода — используются всеми карточными играми |
| `player.go` | Общий вспомогательный тип игрока для карточных игр |
| `bot.go`, `bot_heuristics.go` | Общие для нескольких карточных ботов эвристики и генератор имён ботов (`newBotRoster`) |
| `meld.go` | Логика мелдов (сетов/последовательностей), используется Тонком |

### Каждая игра: три (иногда четыре) файла по своему шаблону

Для игр с ботом принят единый шаблон из трёх файлов:

- **`<игра>_game.go`** — чистое состояние партии и правила: структуры
  данных, конструктор `New...Game(...)`, методы применения ходов,
  определение результата. Никакого Bubble Tea, никакого ввода-вывода
  — это чистая логика, которую тестируют без построения интерфейса.
- **`<игра>_bot.go`** — стратегия бота: `type ...Bot struct`,
  `DecideAction`/`Move` и подобное. Уровни сложности (`Easy`/
  `Medium`/`Hard`, где есть) определены здесь же.
- **`<игра>_tui.go`** — обёртка Bubble Tea: `type ...Model struct`,
  `Update`/`View`, обработка нажатий клавиш, отрисовка.

Игры без бота (Косынка, Сапёр) обходятся без `_bot.go`. У игр с
сохранением на диске (Странник, Трупные батончики, сторимод) есть
ещё и **`<игра>_save.go`**.

| Игра | Файлы |
|---|---|
| Тонк | `game.go`, `bot.go` (часть), `tui.go` — исторически первая игра, поэтому без префикса |
| Дурак | `durak_game.go`, `durak_bot.go`, `durak_tui.go`, `durak_deck.go` (своя колода на 36 карт) |
| Блэкджек | `blackjack_game.go`, `blackjack_bot.go`, `blackjack_tui.go` |
| 101 | `oneohone_game.go`, `oneohone_bot.go`, `oneohone_tui.go` |
| 1000 | `thousand_game.go`, `thousand_bot.go`, `thousand_tui.go` |
| Косынка | `klondike_game.go`, `klondike_tui.go` (без бота — пасьянс) |
| Шашки | `checkers_game.go`, `checkers_bot.go`, `checkers_tui.go` |
| Шахматы | `chess_game.go`, `chess_bot.go`, `chess_tui.go` |
| Го | `go_game.go`, `go_bot.go`, `go_tui.go` |
| Сапёр | `minesweeper_game.go`, `minesweeper_tui.go` (без бота — головоломка) |
| Крестики-нолики | `tictactoe_game.go`, `tictactoe_bot.go`, `tictactoe_tui.go` |
| Нарды | `nardy_game.go`, `nardy_bot.go`, `nardy_tui.go` |
| Игра Ур | `ur_game.go`, `ur_bot.go`, `ur_tui.go` |
| Сенет | `senet_game.go`, `senet_bot.go`, `senet_tui.go` |
| Покер | `poker_game.go`, `poker_bot.go`, `poker_hand.go` (оценка комбинаций), `poker_tui.go` |
| Трупные батончики | `corpsestarch_game.go`, `corpsestarch_tui.go`, `corpsestarch_save.go` |
| Странник | `wayfarer_ship.go` (состояние корабля/капитала), `wayfarer_galaxy.go` (карта звёздной системы), `wayfarer_economy.go`, `wayfarer_combat.go`, `wayfarer_encounters.go`, `wayfarer_env.go`, `wayfarer_quests.go`/`wayfarer_quest_state.go`/`wayfarer_quest_loader.go` (квесты), `wayfarer_tui.go`, `wayfarer_save.go` |
| Сторимод | `story_game.go`, `story_tui.go`, `story_save.go` — разбор ниже, в разделе 3 |

Странник — самая крупная игра, поэтому единственная, где движок
разнесён по смыслу на 9 файлов вместо одного `_game.go`.

### Тесты

Для каждого `<файл>.go` есть парный `<файл>_test.go` — тесты лежат
рядом с тем, что тестируют, а не в отдельном дереве. Общее число
тестов на момент этого файла — около 940.

## 2. Сохранения

Только три игры коллекции пишут что-либо на диск — у остальных 14
партия начинается с чистого листа при каждом запуске, и никакие
настройки (сложность, вариант правил) между запусками не
запоминаются.

| Игра | Файл сохранения | Что внутри |
|---|---|---|
| Странник | `wayfarer_save.go` | `WayfarerShip` — корабль, груз, капитал, прогресс квестов |
| Трупные батончики | `corpsestarch_save.go` | `CorpseStarchGameState` — весь прогресс кликера, включая переход на сторону Хаоса |
| Сторимод | `story_save.go` | `StoryModeState` — см. раздел 3 |

Путь у всех трёх один и тот же шаблон — системная конфигурационная
директория пользователя (`os.UserConfigDir()` в Go: `~/.config` на
Linux, `~/Library/Application Support` на macOS, `%AppData%` на
Windows) плюс общая поддиректория `go-games-collection`:

```
~/.config/go-games-collection/wayfarer_save.json
~/.config/go-games-collection/corpsestarch_save.json
~/.config/go-games-collection/story_save.json
```

Формат — обычный `json.MarshalIndent` прямо по Go-структуре, без
отдельной описанной схемы: что в структуре, то и в JSON, поля один в
один по именам. У Странника и Трупных батончиков при загрузке старого
сохранения есть миграция недостающих полей (на случай, если
сохранение создано более ранней версией игры, где каких-то полей ещё
не было) — у сторимода такой миграции пока нет, он младше и ещё не
переживал смену формата при существующих сохранениях.

Каждый из трёх файлов сохранения полностью независим от двух других
— сброс прогресса в одной игре не трогает остальные.

## 3. Режим истории (сторимод) — устройство подробно

### 3.1. Общая идея

Сторимод — надстройка над обычными играми коллекции: выбираешь
сложность один раз в начале, дальше играешь в любые из 15 подключённых
игр (все, кроме Странника и Трупных батончиков — см. ниже почему), и
победа в каждой начисляет свой уникальный ресурс. Цель — накопить
нужное количество каждого ресурса.

Файлы:

- **`story_game.go`** — вся логика: типы ресурсов, начисление,
  расход, суточные события, показатели выживания. Чистая логика без
  Bubble Tea, как и `<игра>_game.go` у обычных игр.
- **`story_tui.go`** — экраны сторимода (хаб, выбор сложности,
  приветствия, использование ресурсов, скрытая концовка) и реестр
  подключённых игр (`storyGameDefs`) с условием победы для каждой.
- **`story_save.go`** — сохранение/загрузка/удаление, тот же шаблон,
  что у Странника и Батончиков.
- Диспетчеризация состояний сторимода (какое состояние ведёт в
  какое) прописана в общем `menu.go`, наравне с обычным меню.

### 3.2. Почему только 15 игр из 17

Странник (открытый мир без единого условия "партия окончена") и
Трупные батончики (кликер без дискретной победы/поражения) не
вписываются в модель "победил — получил ресурс". Обе доступны как
обычно в режиме "просто игры", но в сторимоде просто отсутствуют.

### 3.3. Ресурсы — таблица целиком

Один ресурс на игру, идентификатор — `StoryResourceID` (перечисление
в `story_game.go`), в этом же порядке показывается в хабе:

| Игра | Ресурс | Цель | Условие начисления |
|---|---|---|---|
| Тонк | Бутылка воды | 100 | 3+ раунда; баланс не ниже, чем у соперников, при выходе |
| Дурак | Патроны для ружья | 100 | 3 партии подряд без "дурака" |
| Шашки | Банка тушёнки | 100 | Победа |
| Нарды | Сигарета | 100 | Победа |
| Блэкджек | Самогон | 100 | 3+ раунда; баланс выше стартового при выходе |
| Шахматы | Аптечка | 100 | Победа |
| Сапёр | Антидот | 100 | 3 партии подряд без взрыва |
| Го | Фильтр для воздуха | 100 | Победа |
| Игра Ур | Спички | 100 | Победа |
| Сенет | Верёвка | 100 | Победа |
| 101 | Батарейки | 100 | Победа во всём матче (не в отдельном раунде) |
| 1000 | Изолента | 100 | 3+ раздачи; первое место по очкам при выходе |
| Косынка | Антидепрессант | 100 | 3 победы **за один день** (не подряд, не общий счётчик) |
| Крестики-нолики | Кусок мыла | **10** | Победа **или ничья** |
| Покер | Золотые зубы | 100 | Победа во всём турнире |

Целевые числа — отдельные именованные константы
(`StoryTargetTonk`, `StoryTargetDurak`, ...), а не одно общее число,
специально для того, чтобы их было легко подправить по отдельности.

Условия победы реализованы как функции `storyOutcome<Игра>(m
tea.Model) (finished, won bool)` в `story_tui.go` — каждая проверяет
конкретное поле результата СВОЕЙ игры (`Result.Winner`,
`RoundsPlayed`, и т.п.). Три игры (Тонк, Блэкджек, 1000) потребовали
добавить в их собственные `_game.go` счётчик `RoundsPlayed`/`HandNumber`
— минимальное дополнение, не влияющее на обычную игру вне сторимода.
Дурак и Сапёр хранят "серию без поражения" прямо в своей `Model`
(`storyNonFoolStreak`/`storyWinStreak`) — поле, которого не существует
для обычного режима "просто игры".

### 3.4. Начисление ресурса — суточный лимит

Победа сама по себе не гарантирует ресурс: `AwardResource` (в
`story_game.go`) пропускает начисление, если сегодня уже случилось
`StoryDailyGrantsLimit` (= 3) начислений — играть можно сколько
угодно, просто пятая-шестая победа за день ничего не даст. У Косынки
это накладывается НА её собственное правило "3 победы за день" —
сначала должно сработать правило Косынки, и только потом на этот факт
начисления натягивается общий суточный лимит.

Счётчик `DailyGrantsUsed` (как и `KlondikeWinsToday`) сбрасывается в
`Tick()` при переходе на новые виртуальные сутки.

### 3.5. Запирание в сейф — и что это НЕ значит

Как только `Resources[id] >= Target`, ресурс помечается
`Locked[id] = true`. Это НЕ блокирует ни саму игру (можно продолжать
играть и дальше копить тот же ресурс без верхнего предела), ни
расход — единственный эффект: пока ресурс заперт, суточные события,
способные его как-то уменьшить, его не трогают (сейчас таких событий,
уменьшающих СЧЁТ ресурса, нет — есть только расход самим игроком,
`spendResource`, который снимает пометку `Locked`, если после траты
осталось меньше цели).

### 3.6. Этап знакомства (онбординг)

Новая партия сторимода не сразу открывает все 15 игр. Три этапа
(`StoryOnboardingStage` в `story_game.go`, монотонное продвижение
только вперёд — не завязано на текущие значения ресурсов, чтобы
суточные события их не откатили):

1. **Только крестики-нолики.** Числа ресурсов и весь остальной
   антураж лагеря скрыты.
2. **+ Шашки** — после `storyStartingAmount + 3` очков ресурса
   крестиков-ноликов (то есть 3 реальных победы/ничьих сверх
   стартовых трёх).
3. **Обычный режим** — после `storyStartingAmount + 1` очков ресурса
   шашек (1 победа). В момент перехода на этот этап показывается
   одноразовое приветствие от ИИ убежища (`stateStoryWelcome`,
   печатается по слову каждые 250мс) — и только оно, никогда больше
   не повторяется для этой партии.

### 3.7. Показатели выживания

Три процентных показателя (0–100), видны в лагере только после
завершения знакомства:

- **Стресс** (`Stress`) — не опускается ниже `StoryStressFloor` (20)
  сам по себе, но антидепрессант может увести его вплоть до 0, с
  последующим часовым восстановлением обратно к 20 (см. 3.8).
- **Отравление** (`Poisoning`).
- **Токсин в воздухе** (`ToxinLevel`).

Ни один из трёх не меняется от одного факта течения времени — только
по конкретным событиям (см. 3.9) и по расходу ресурсов (см. 3.8).

### 3.8. Расходуемые ресурсы — экран `[u]` в лагере

Четыре ресурса имеют не только "цель для сейфа", но и практический
расходуемый эффект (`storyUseItemDefs` в `story_tui.go`):

| Ресурс | Эффект (метод в `story_game.go`) |
|---|---|
| Антидепрессант (Косынка) | `SpendAntidepressant` — стресс −20%, может уйти ниже пола вплоть до 0; если ушёл ниже пола, запускает часовое восстановление обратно к 20% (`ApplyStressRecovery`, линейная интерполяция, как и очистка воздуха ниже) |
| Антидот (Сапёр) | `SpendAntidote` — отравление −20%, не ниже 0 |
| Фильтр для воздуха (Го) | `SpendAirFilter` — отмечает фильтр использованным сегодня (`FilterUsedToday`), что на сегодняшние сутки снимает риск выброса нейротоксина (см. 3.9) и при обработке суток сбрасывает счётчик дней без замены |
| Батарейки (101) | `SpendBattery` — запускает очистку воздуха: токсин плавно идёт к 0 в течение часа (`ApplyAirPurification`) |

Оба "часовых" эффекта (восстановление стресса, очистка воздуха)
устроены одинаково: запоминается начальное значение и момент запуска,
а при каждом входе в лагерь (`enterStoryHub`/
`enterStoryHubFromModeSelect`) линейно интерполируется текущее
значение по прошедшему времени, вплоть до полного завершения через
час.

Трата ресурса (`spendResource`) снимает пометку `Locked`, если после
списания остаток опустился ниже цели — расход реально расходует
накопленное, а не просто "ест" бесплатный излишек сверху.

### 3.9. Суточные события — вероятности

Оба события разыгрываются в `processDayEvents` (`story_game.go`),
по одному разу за каждые виртуальные сутки, обработанные в `Tick`
(если игрок не заходил несколько дней подряд, каждый день
розыгрывается отдельно, а не одним махом).

**Выброс нейротоксина** — зависит от того, сколько суток подряд
фильтр для воздуха НЕ менялся (`DaysSinceFilterUsed`,
`storyNeurotoxinProbability`):

| Суток без замены фильтра | Вероятность выброса за эти сутки |
|---|---|
| 0 (фильтр менялся сегодня) | 0% |
| 1 | 50% |
| 2 | 75% |
| 3 и более | 100% (гарантированно) |

Если выброс произошёл — токсин в воздухе растёт на случайное
значение от 10% до 70% (равномерно, `10 + rnd.Intn(61)`), с
насыщением на 100%. Счётчик дней без фильтра НЕ сбрасывается самим
фактом выброса — только реальной заменой фильтра, так что при долгом
пренебрежении выбросы могут случаться несколько дней подряд один за
другим.

**Стук в дверь** — не зависит ни от какого ресурса, только от того,
сколько суток его не было (`DaysSinceDoorKnock`,
`storyDoorKnockProbability`):

| Суток без стука | Вероятность за эти сутки |
|---|---|
| 0 | 0% |
| 1 | 10% |
| 2 | 50% |
| 3 и более | 100% |

Если событие происходит — стресс +20% (потолок 100%), счётчик
сбрасывается. Этот прирост стресса НЕ уходит сам по себе — снять его
можно только антидепрессантом.

Оба события показываются игроку только при входе через меню режимов
(`enterStoryHubFromModeSelect`) — не при обычном возврате из партии
(`enterStoryHub`), чтобы не прерывать уже идущую игровую сессию
всплывающими уведомлениями после каждой отдельной партии. Флаги
`PendingNeurotoxinAlert`/`PendingDoorKnockAlert` копятся до следующего
входа через меню и показываются по очереди, после приветствия дня.

### 3.10. Приветствие дня

Тоже только при входе через меню режимов, одно из трёх
(`storyGreetingForDays`, по числу суток с прошлого такого входа):

| Суток с прошлого входа | Приветствие |
|---|---|
| 0 (тот же день) | «Снова решил поиграть? Смотри, чтобы не началась зависимость.» |
| 1 | «Ты проснулся! Возьми свой дневной паёк.» |
| 2 и более | «Я думала с тобой что-то случилось!..» |

Плюс при каждом обычном возврате из партии (не через меню) в лагере
показывается одна случайная короткая фраза-наблюдение из пула 12
штук (`storyPostGameFlavorKeys`) — про пульс, дыхание, зрачки и т.п.,
от лица ИИ убежища.

### 3.11. Скрытая концовка

Пункт «Сбежать из бункера» появляется в конце списка игр в лагере,
когда одновременно выполнены **все три** условия
(`storyEscapeUnlocked`):

- Кусок мыла (Крестики-нолики) ≥ 50
- Верёвка (Сенет) ≥ 50
- Стресс ≥ 60%

Выбор пункта ведёт на экран уговоров остаться (`stateStoryEscapeAttempt`) с двумя вариантами: принять успокоительное
(стресс мгновенно падает до 0, без последующего часового
восстановления — в отличие от антидепрессанта) или закончить игру
досрочно (ведёт на финальный экран и обратно в меню режимов;
сохранение сторимода при этом не удаляется).

### 3.12. Сброс прогресса

Клавиша `[N]` в лагере (доступна и на этапе знакомства) запрашивает
подтверждение (`y`/`n`), и по «да» удаляет `story_save.json` и ведёт
на экран выбора сложности заново — тот же паттерн `N` + подтверждение,
что уже был в Трупных батончиках.