# План развития и актуальные задачи

Живой документ планирования: сюда сходятся планы на развитие, актуальные
задачи и проработка крупных направлений. Срез-статус архитектуры —
`docs/demo.md` (дорожная карта там — историческая, актуальный план здесь).

Дата ревизии: 2026-09-06.

---

## Актуальные задачи

| # | Задача | Статус |
|---|--------|--------|
| 1 | Срез «меньше ошибок»: реестры ID, pre-commit, разрезание LocationScene, фикстуры, fail-fast waitFor | ✅ сделано (c379f20, 16b59d8, 39c6349) |
| 2 | AI-генерация текстур и спрайтов (работа B, ниже) | 📋 спланировано, отложено |
| 3 | AI-генерация аудио (работа A, ниже) | 📋 спланировано, отложено |
| 4 | Акт 2: новые локации/сюжет по `docs/world.md` | очередь после акта 1+AI-ассетов |
| 5 | Замена сгенерированных плейсхолдеров арта на AI/ручной арт | в составе работы B |

Приоритет между работами A и B: **B (изображения) выше** — визуальный стиль
блокирует восприятие акта 2; аудио сейчас закрывается процедурным генератором
(`tools/audio/gen.mjs`) приемлемо.

---

## Ограничения (читать первым)

- **Машина разработки: Intel HD 620 (iGPU, нет CUDA), 15 ГБ RAM, 4 ядра CPU.**
  Только CPU-инференс. Модели класса SDXL/FLUX/SANA/DreamLite отпадают либо
  как «медленный офлайн-пакет» (десятки минут на картинку). Целевой класс —
  компактные модели (< 1.5B параметров) и INT8/4-бит квантизация, CPU-рантаймы.
- **Стиль игры жёсткий**: палитра 32 цветов (`tools/pixelart/palette.mjs`),
  размеры спрайтов по `docs/art-style.md`, pixel-perfect. Любая AI-генерация —
  только как **сырьё** с обязательной пост-обработкой: даунскейл nearest,
  квантизация в палитру, проверка чек-листом арт-библии. AI-вывод не попадает
  в `assets/` напрямую.
- **Формат аудио фиксирован**: моно 22050 Гц, 16-бит WAV
  (`tools/audio/gen.mjs`). AI-вывод приводится к нему (ffmpeg: sample rate,
  моно, нормализация, обрезка тишины).
- **Лицензии весов**: для игры важен коммерчески-допустимый статус. Отмечено в
  таблицах; некоммерческие веса (CC BY-NC) — только для экспериментов/PoC.
- **Детерминизм**: у всего пайплайна фиксированный seed в конфиге генерации —
  регенерация не должна молча менять ассеты (аналогично `npm run maps:fresh`).

---

## Работа B — AI-генерация текстур и спрайтов

### Классы потребностей

1. **Тайлы** (трава, пепел, вода…) — процедурный генератор уже даёт приемлемый
   результат; AI ценен для сложных поверхностей (бутеи, руины, интерьеры).
2. **Спрайты объектов** (предметы, декор, интерактивы) — главная точка роста:
   сейчас Graphics-плейсхолдеры.
3. **Спрайты персонажей + атласы** (герой, NPC, враги, кадры анимаций) — самое
   сложное: консистентность кадров, фиксированные размеры листа
   (`hero_sheet.png` — контракт арт-библии).

### Кандидаты

| Модель | Размер | Железо | Нативная палитра | Лицензия | Комментарий |
|--------|--------|--------|------------------|----------|-------------|
| **PXG-Tiny** (HF: Tarul/pxg-tiny) | 483K | CPU, NumPy, 1.8 МБ | да (прямые индексы) | MIT + CC0 | 16×16, 38 классов. Идеален по железу, но узкий домен |
| **PixelGPT-24×24** (unstonio) | 68M | CPU, секунды | да, 5 цветов | MIT | 24×24 спрайты; дообучение под свою палитру реально |
| **Pixel Forge** (cochranblock) | 1.1–17M | CPU (Rust) | да, 7 встроенных палитр | Unlicense | 108 классов объектов; нет персонажей-атласов |
| **Retro Diffusion SD1.5** (LostMedia, архив) | ~1B | CPU минуты/картинку | нет (пост-обработка) | Public Domain | классика пиксель-диффузии; для офлайн-пакета |
| **Retro Diffusion API (RD Plus/Tile/Animation)** | облако | — | да | платный API | лучший результат для тайлов/анимаций; фолбэк, если локальное не тянет |
| **LPC-style (PIXEL-T2I и др.)** | research | GPU | нет | research | перспективное направление для атласов 4 ракурса × walk/slash |

Вывод по классам: тайлы и объекты — **GPT-пиксель-модели локально** (PXG-Tiny /
Pixel Forge / дообученный PixelGPT под нашу палитру); персонажи-атласы — пока
**не решено локально** (кандидаты: дообучение PixelGPT на своих кадрах, либо
платный RD API, либо ручной арт поверх AI-болванок).

### Пайплайн интеграции (проект решения)

```
tools/aiart/gen.mjs        # вызов модели (seed, промпт из манифеста)
  → tools/aiart/post.mjs   # даунскейл nearest → квантизация palette.mjs → дедуп
  → tools/aiart/manifest.json  # список ассетов: промпт, seed, размер, статус
  → apps/game/assets/…     # только после ручного апрува (review-каталог)
```

Принципы: манифест-драйвен (как `maps/`); апрув-гейт (человек смотрит обзорный
лист перед попаданием в игру); ревизия в git; проверка стиля — чек-лист
`docs/art-style.md` + скриншот-смоук.

### Этапы

- **B0 (PoC, ~1 вечер)**: запустить PXG-Tiny/Pixel Forge локально на CPU;
  сгенерировать 10–20 объектов, прогнать пост-обработку, сравнить с текущими
  плейсхолдерами. Критерий: «хотя бы 30% годных без ручной правки».
  ✅ **Выполнен (2026-09-06)**: PXG-Tiny на CPU (~6 с/спрайт), 20 спрайтов,
  40% годных, стиль совпал с игрой на 100%. Пайплайн: `tools/aiart/`
  (`post.mjs` — кроп/квантизация в палитру + обзорный лист; `manifest.json`
  — вердикты). Pixel Forge отложен (нет Rust-тулчейна). Ограничение:
  критичные для игры ассеты (колодец, столб, рычаг, колокольчик, моты)
  вне 38 классов модели — для них дообучение / RD API / ручной арт.
- **B1**: пайплайн post.mjs + манифест + review-каталог; генерация партии
  спрайтов объектов для акта 2.
- **B2**: тайлы сложных поверхностей (img-условность от существующих тайлов).
- **B3**: эксперимент с персонажами/атласами (дообучение или RD API) — по
  итогам B1–B2 решить, не откладывать ли до ручного арта.

---

## Работа A — AI-генерация аудио

### Классы потребностей (по пользовательскому сценарию)

| Класс | Что это сейчас | AI-кандидат | Железо |
|-------|----------------|-------------|--------|
| **Окружение** (ветер, пепел, вода прудов) | процедурный шум в gen.mjs | **Stable Audio 3 Small-SFX** (433M, CPU, 120 с) — длинные лупы; луповальность через crossfade-склейку | CPU ок |
| **SFX взаимодействия** (шаги, клик, удар, звон) | gen.mjs, приемлемо | **Stable Audio 3 Small-SFX** (тот же рантайм; seed-детерминизм для вариантов) | CPU ок (~секунды-десятки секунд на клип на 4 ядрах) |
| **Музыка: фоновые лупы** | gen.mjs (треки 3 областей) | **Stable Audio 3 Small-Music** (433M, CPU, 120 с) — короткие лупы; либо **ACE-Step 1.5** 2B turbo INT8 (CPU-медленно: минуты-десятки минут на трек, но офлайн-пакет) | Small-Music — да; ACE-Step — терпимо для пакета |
| **Музыка: катсцены/сюжетные моменты** | нет (трек + звон) | **ACE-Step 1.5** — полноценные треки с настроением/структурой, стемы; MusicGen small — фолбэк для мелодических заготовок | офлайн-пакет, не hot-reload |

### Кандидаты (сводно)

| Модель | Размер | VRAM/железо | Длина | Лицензия | Роль у нас |
|--------|--------|-------------|-------|----------|------------|
| **Stable Audio 3 Small-SFX / Small-Music** | 433M | CPU (TFLite), ~1.9 ГБ пик | 120 с | веса: Stability Community License; код MIT | основной локальный рантайм для SFX + лупов |
| **ACE-Step 1.5** | 2B (turbo INT8) | CPU (медленно), GPU <4 ГБ | 10 с–10 мин, стемы | MIT | музыка катсцен/сюжета, офлайн-пакет |
| MusicGen small (AudioCraft) | 300M | CPU ~4 ГБ RAM | ~30 с | MIT/CC-BY-NC веса | фолбэк, мелодия-условность |
| Stable Audio Open 1.0 | 1.2B | GPU ~2.5–8 ГБ | 47 с | Stability Community | зрелый, но на нашей машине безнадёжно медленный; пропускаем |

### Пайплайн интеграции (проект решения)

```
tools/aiaudio/gen.mjs       # вызов модели, seed, промпт из манифеста (аналог aiart)
  → post: ffmpeg → 22050 моно 16-bit → нормализация → crossfade-луп для music/ambience
  → review-каталог → apps/game/assets/audio/{sfx,music}/*.wav
```

Принципы те же: манифест, апрув-гейт, seed-детерминизм, формат игры не меняется
(шины master/music/sfx в движке уже готовы). Лупы проверять скриптом
(стык начала/конца без щелчка).

### Этапы

- **A0 (PoC)**: Stable Audio 3 Small-SFX локально на CPU; сгенерировать 5
  SFX-замен (step, ui_click, bell_hit) + 1 амбиент-луп прудов. Критерий: звук
  лучше процедурного на слух и формат сходится.
- **A1**: пайплайн aiaudio + манифест; замена SFX, амбиент-лупы областей.
- **A2**: музыкальные лупы (Small-Music), сравнение с gen.mjs-треками.
- **A3**: ACE-Step офлайн-пакет для катсцен акта 2 (1–2 трека под моменты).

---

## Открытые решения (принять перед стартом работ)

1. B0: какая из GPT-пиксель-моделей заходит лучше на нашем домене — брать обе
   на пробу? (обе крошечные, сравнение дешёвое)
2. Персонажи-атласы: дообучение локально vs платный RD API vs ручной арт —
   решить после B1/B2.
3. Python-окружение для моделей: uv-venv вне репо? Веса кэш в ~/.cache — в git
   не попадают; в репо — только манифесты и итоговые ассеты.
4. Порог апрува: кто смотрит review-лист (пользователь) и где фиксируется
   вердикт (пометка в манифесте).

## Что НЕ делаем

- Облачные API в основном пайплайне (только как опциональный фолбэк для спрайтов).
- Модели с некоммерческими весами в основном пайплайне (DreamLite CC BY-NC —
  только эксперименты).
- TTS-голоса персонажей — вне среза, кандидат на будущее: Kokoro-82M (CPU).