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

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

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

---

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

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

Приоритет между работами 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** (github.com/unstonio/pixelgpt-24x24) | 68M | CPU, ~22 с | да, 5 цветов/спрайт, кастомная палитра на запрос | **нет (не указана)** | 24×24; отказов нет, домен тянет частично (см. B1). Веса в репо; датасет 20K — CC BY 4.0 |
| **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 |

Вывод по классам (после B0+B1): инвентарь/декор — **PXG-Tiny локально** (её
классы); простые объекты 24×24 — PixelGPT (но лицензии нет — только PoC);
критичные интерактивы и тайлы сложных поверхностей — **RD API (платный) или
ручной арт**; дообучение под игру не делаем. Персонажи-атласы — **не решено**
(кандидаты: платный 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 (домен, вторая модель)**: PixelGPT-24×24 на доменных интерактивах
  (промпты + обусловливание палитрой игры из 5 цветов).
  ✅ **Выполнен (2026-09-06)**: 18 спрайтов, 44% годных, **отказов нет** —
  доменные объекты (колокол, дверь, камин, столб, моты) модель рисует, где
  PXG-Tiny отказывала. Ограничения: даунскейл 24→16 губит деталь (колодец
  good на 24×24), фон часто залит, ровно 5 цветов, ~22 с/спрайт CPU,
  **лицензии на код/веса нет — в игру нельзя**. Манифест: `manifest-b1.json`.
- **B2**: тайлы сложных поверхностей (img-условность от существующих тайлов) —
  локальным моделям недоступно, кандидат RD API; отложено.
- **B3**: персонажи/атласы — RD API (платный) или ручной арт; отложено
  до потребности акта 2.

---

## Работа C — крупные объекты (footprint + большие спрайты)

Акт 2 захочет здания и крупные деревья — объекты больше 1×1 тайла. Сегодня
движок умеет только `TallSpec` (1 тайл footprint + произвольная высота) и
ручной `blocked`. Большой спрайт, якоренный в один тайл, сортируется глубиной
по точке — герой сбоку от дома перекрывается неверно.

### Что нужно

1. **Движок: footprint w×h** — коллизия по всему прямоугольнику, земля под ним,
   спрайт якорем низ-центр footprint'а; глубина по прямоугольнику
   (`(x+w-1)+(y+h-1)`, `IsoDepthLayer.addRect`), а не по точке якоря.
2. **Арт-библия: слоты крупных спрайтов** — фиксированные размеры с якорями
   (дом 3×3, большое здание 4×4…), чтобы любой источник рисовал в готовый слот.
3. **Арт: три пути** — крупный объект кодом в `gen.mjs` (композит: модули стен +
   крыша — наш бесплатный путь); апскейл nearest из 24×24 (только болванка —
   чужая плотность пикселя рядом со спрайтами 1×); RD API (умеет большие
   размеры и тайлы, платный).

### Этапы

- **C0 (движок) ✅**: `props` в `TileMapData` (footprint, коллизия по всему
  прямоугольнику, земля под ним), `IsoDepthLayer.addRect` (глубина по
  диагонали юго-восточного угла footprint'а), валидация в `mapFormat`,
  тесты; `LocationScene` вставляет `map.propViews` в общий depth-слой.
- **C1 (арт-библия) ✅**: слоты крупных спрайтов в `docs/art-style.md`
  (дом 2×2 — 64×80, дом 3×3 — 96×96, здание 4×4 — 128×112; якорь ставит
  движок). Плотность пикселя — как у тайлов; AI-апскейл в слоты не попадает.
- **C2 (проба) ✅**: большой дом 2×2 кодом в `gen.mjs`
  (`tiles/house_big.png`, 64×80, композит: модули щитов + крыша шпал +
  козырёк + окна) против апскейл-болванок 24→48 из B1
  (`apps/game/tools/aiart/probe-c2.png`). Вывод: **для крупных объектов —
  код-композит в `gen.mjs`**; апскейл даёт мыло с чужой плотностью пикселя и
  залитым фоном (только черновая болванка), нативно больших размеров локальные
  модели не умеют. RD API остаётся опцией, если код-композита не хватит.

---

## Работа 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-пиксель-моделей заходит лучше~~ — **закрыто B0+B1**:
   PXG-Tiny — инвентарь/декор, PixelGPT-24×24 — домен частично, но лицензии нет.
2. ~~Персонажи-атласы: дообучение локально vs RD API vs ручной арт~~ —
   дообучение под игру **отвергнуто**; осталось: платный RD API vs ручной арт.
3. ~~Python-окружение~~ — **закрыто**: venv вне репо (`~/.cache/rpg-ai/venv`,
   `venv-pxgpt`), веса в `~/.cache/rpg-ai/`; в git — манифесты и review-PNG.
4. Порог апрува: кто смотрит review-лист (пользователь) и где фиксируется
   вердикт (пометка в манифесте).

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

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