diff --git a/CLAUDE.md b/CLAUDE.md index 6fec5a7..16ccb61 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -51,6 +51,7 @@ - `docs/llms.txt` — **точка входа для ИИ-агента**: карта всех док одной строкой на док. - `docs/engine/` — **документация движка** (по-русски): `README.md` (архитектура и принципы), `getting-started.md`, `core.md`, `render.md`, `input.md`, `maps.md`, `ui-and-dialogue.md`, `cutscene.md`, `assets-audio-save.md`, `art-pipeline.md`, `recipes.md`, `agent.md` (агентный мост), `practices.md` (живой документ практик агента). При изменении API движка обновляй соответствующий файл и `practices.md` (если появился новый приём) **в том же коммите**. - `docs/demo.md` — **внутренняя проектная дока среза**: матрица «подсистема движка → где показана в игре» + статус, боевая модель, архитектура, дорожная карта. +- `docs/plan.md` — **живой план развития**: актуальные задачи, проработка крупных направлений (AI-генерация спрайтов/аудио, ограничения железа). Новые планы вести здесь. - `docs/world.md` — библия мира (сеттинг, локации, персонажи, сюжет). **Любой новый контент сверять с ней.** - `docs/art-style.md` — арт-библия: палитра (32 цвета), размеры спрайтов, правила стиля, чеклист ассетов. - `packages/engine/src/` — модули движка: `core/` (Engine, GameLoop, Tween, GameState, StateMachine, Settings, EventBus), `scene/` (SceneManager + fade-переходы), `render/` (Renderer, Camera, IsoDepthLayer, Particles, scale), `input/` (действия, геймпад, VirtualJoystick), `map/` (изометрия, A*, mapFormat, Tiled-импорт), `ui/` (PixelText/VT323, Panel, Button, MenuList, DialogueBox), `dialogue/` (DialogueRunner — view-агностик), `audio/` (шины master/music/sfx), `assets/` (AssetLoader + атласы), `save/`, `math/` (iso, rng, easing). diff --git a/docs/llms.txt b/docs/llms.txt index 9931124..0545e33 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -36,4 +36,5 @@ - [Библия мира](world.md): сеттинг, локации, персонажи, сюжет — сверять любой новый контент. - [Арт-библия](art-style.md): палитра 32 цвета, размеры спрайтов, правила стиля. -- [Срез демо](demo.md): матрица «подсистема → где показана», статус, дорожная карта. \ No newline at end of file +- [Срез демо](demo.md): матрица «подсистема → где показана», статус, дорожная карта. +- [План развития](plan.md): актуальные задачи и проработка крупных направлений (AI-генерация спрайтов и аудио). \ No newline at end of file diff --git a/docs/plan.md b/docs/plan.md new file mode 100644 index 0000000..daef3b7 --- /dev/null +++ b/docs/plan.md @@ -0,0 +1,161 @@ +# План развития и актуальные задачи + +Живой документ планирования: сюда сходятся планы на развитие, актуальные +задачи и проработка крупных направлений. Срез-статус архитектуры — +`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% годных без ручной правки». +- **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). \ No newline at end of file