Dungeons-Ground/PLAN.md

Dungeons & Ground — план закрытой web‑альфы

1. Цель продукта

Dungeons & Ground — англоязычная веб‑платформа для текстовых TTRPG‑кампаний любого жанра, где:

• AI‑соавтор помогает за несколько сообщений создать собственную вселенную.
• AI Game Master ведёт историю, NPC и последствия.
• Реальные игроки участвуют асинхронно в общем пошаговом чате.
• Постоянные AI‑герои дополняют партию, а при необходимости временно заменяют отсутствующих игроков.
• Сервер, а не языковая модель, рассчитывает проверки, броски, HP и урон.
• Кампания сохраняет мир, отношения, инвентарь, события и долгосрочную память.

Главный критерий готовности альфы: 2–4 человека создают мир, персонажей и проходят минимум 20–30 минут связной кампании, причём AI не забывает ключевые события и не изменяет игровые значения произвольно.

В отличие от Friends & Fables, уже совмещающего AI‑ведущего, worldbuilding, память, карты, бой и мультиплеер, первая версия D&G сосредоточится на простом создании мира и партии, которая продолжает игру даже при отсутствии части людей. Возможности Friends & Fables, описание их системы памяти.

2. Функциональность альфы

Пользовательский путь

1. Вход по email magic link для пользователей из allowlist.
2. Создание приватной вселенной через чат с AI‑соавтором.
3. AI задаёт 3–5 уточняющих вопросов о жанре, атмосфере, конфликте и желаемой роли игроков.
4. Создаётся редактируемый стартовый набор:
   • premise, genre, tone и content boundaries;
   • стартовая локация;
   • 3 значимых NPC;
   • 2 фракции;
   • сюжетная завязка;
   • скрытая угроза или цель;
   • начальная сцена.
5. Владелец подтверждает мир, создаёт кампанию и приглашает игроков ссылкой.
6. Каждый игрок создаёт персонажа вручную или с помощью AI.
7. Владелец добавляет постоянных AI‑героев и определяет, чьи персонажи могут временно переходить под управление AI.
8. Игроки отправляют действия в текущем раунде.
9. AI‑DM обрабатывает раунд, когда:
   • ответили все активные реальные игроки; или
   • владелец нажал Continue without waiting.
10. AI‑герои и замены совершают действия после людей, затем AI‑DM публикует единый результат раунда.

Облегчённая игровая система

Использовать классические характеристики STR, DEX, CON, INT, WIS, CHA во всех жанрах, но позволять AI адаптировать названия архетипов, экипировки и способностей под fantasy, sci‑fi, horror и другие сеттинги.

Первая версия движка покрывает:

• d20 ability и skill checks;
• proficiency bonus;
• HP, Defense/AC и initiative;
• attack roll, damage и healing;
• advantage/disadvantage;
• простые статусы и ограниченные ресурсы;
• серверный генератор случайных чисел с сохранением формулы и результата;
• ручную корректировку состояния владельцем кампании с записью в аудит.

Полные классы, заклинания, сетка боя и редкие правила 5e не входят в альфу. Основа — SRD 5.2.1 под CC BY 4.0 с обязательной атрибуцией; закрытые названия и сеттинги D&D не использовать. Официальные условия SRD 5.2.1.

Память и состояние мира

Хранить отдельно:

• неизменяемый журнал действий и результатов;
• текущую сцену и активные сущности;
• структурированное состояние персонажей, NPC, фракций и заданий;
• отношения между персонажами;
• важные воспоминания с привязкой к персонажам, локациям и тегам;
• краткое резюме истории, обновляемое каждые три завершённых раунда.

В контекст модели передавать только системные инструкции, текущую сцену, последние два раунда, участвующие сущности, активные цели и релевантные воспоминания. Полная история никогда не отправляется автоматически.

3. Техническая архитектура

Стек

• Monorepo на TypeScript.
• Nuxt.js для SSR‑интерфейса и Nitro API.
• Отдельный TypeScript worker для генерации миров и обработки игровых раундов.
• Supabase: PostgreSQL, Auth, Row Level Security и Realtime.
• BullMQ + managed Redis для очереди AI‑задач.
• Railway: отдельные deployments для Nuxt/Nitro и worker.
• OpenRouter provider adapter с моделью deepseek/deepseek-v4-flash.
• Zod для общей валидации API, AI‑ответов и игровых команд.
• Vitest, Nuxt Test Utils и Playwright для тестов.

Desktop‑версия позднее создаётся через Tauri и использует тот же API и web‑интерфейс.

Основные сущности и интерфейсы

• User, Invite, World, WorldEntity, Campaign, CampaignMember.
• Character, CharacterController, Relationship.
• Round, PlayerIntent, GameEvent, DiceRoll.
• SceneState, QuestState, Memory, StorySummary.
• AiJob, AiUsage, AuditEntry.

Публичные серверные операции:

• создание и редактирование мира через coauthor session;
• подтверждение сгенерированного мира;
• создание кампании и приглашение участника;
• создание/назначение персонажа;
• отправка или изменение действия текущего раунда;
• отметка игрока как готового;
• принудительное закрытие раунда владельцем;
• получение истории, состояния персонажа и активной сцены;
• ручная корректировка состояния владельцем.

Обработка раунда

1. Nitro сохраняет PlayerIntent и готовность игрока.
2. Транзакция блокирует раунд и создаёт ровно одну задачу после выполнения условия закрытия.
3. Worker собирает минимальный контекст.
4. AI определяет намерения, нужные проверки и действия AI‑героев через типизированные tool calls.
5. Rules engine выполняет все броски и изменения механического состояния.
6. Результаты возвращаются AI для финальной narration.
7. Предложенные события и изменения проходят Zod‑валидацию и проверку разрешённых переходов.
8. Narration, события, память и новое состояние сохраняются атомарно.
9. Supabase Realtime обновляет интерфейсы участников.

При timeout или ошибке OpenRouter задача повторяется с idempotency key. После исчерпания повторов раунд остаётся открываемым повторно владельцем; частичные изменения не сохраняются. OpenRouter поддерживает tool calling и JSON Schema outputs, которые следует использовать для типизированных AI‑операций. Tool calling, structured outputs.

4. Дорожная карта на 8–10 недель

Недели 1–2 — фундамент

• Monorepo, Nuxt/Nitro, worker, CI и окружения.
• Supabase Auth, allowlist, RLS и базовая схема данных.
• Англоязычный UI: login, dashboard, world list.
• OpenRouter adapter, учёт токенов, дневные квоты и безопасное хранение ключа.
• Первый вертикальный тест: действие игрока → worker → ответ AI.

Недели 3–4 — вселенные и персонажи

• Coauthor chat и структурированная генерация стартового набора.
• Preview/edit/confirm для мира.
• Создание кампании и персонажей.
• Приглашения, lobby, роли owner/player и AI‑герои.
• 13+ фильтрация входных prompts и выходов модели.

Недели 5–6 — игровой цикл

• Раунды, готовность участников и принудительное продолжение владельцем.
• Realtime‑обновления.
• Rules engine и журнал бросков.
• AI‑DM orchestration, AI‑герои и временная замена отсутствующих игроков.
• Защита от двойной обработки и конфликтующих действий.

Недели 7–8 — память и стабильность

• Game events, relationships, memories и story summaries.
• Контекстный retrieval без векторной базы: сущности, локации, теги и PostgreSQL full‑text search.
• Retry, rate limits, usage dashboard и аудит изменений.
• E2E‑сценарий полной партии и набор AI‑регрессионных тестов.

Недели 9–10 — закрытая альфа

• UX‑полировка, responsive web и onboarding.
• Наблюдаемость: ошибки, latency, стоимость раунда, размер контекста.
• Тестирование командой и приглашёнными пользователями.
• Исправление критических проблем и подготовка формы обратной связи.

5. Проверка и критерии приёмки

Обязательные сценарии:

• Создать fantasy, sci‑fi и horror‑миры через coauthor chat.
• Отклонить или исправить неполную/невалидную AI‑структуру.
• Два пользователя вступают в одну кампанию и видят одинаковое состояние.
• Раунд ждёт всех активных людей.
• Владелец продолжает без отсутствующего игрока, после чего его персонажа корректно подхватывает AI.
• Постоянный AI‑герой сохраняет характер и отношения между сценами.
• Броски воспроизводимо отображают формулу, модификатор и итог.
• LLM не может напрямую изменить HP, инвентарь или результат броска.
• Повторный запрос, reconnect или retry не создаёт второй narration.
• OpenRouter timeout не повреждает состояние кампании.
• Пользователь не видит чужие приватные миры и кампании.
• 13+ фильтр блокирует запрещённый explicit‑контент.
• После 15–20 раундов AI корректно вспоминает ключевое событие из начала игры.
• Средняя стоимость и задержка раунда укладываются в установленные перед альфой квоты.

Перед приглашением внешних тестеров провести минимум 20 сценарных AI‑прогонов с заранее ожидаемыми фактами, правилами и последствиями.

6. Зафиксированные ограничения

• Название Dungeons & Ground считается финальным, но перед публичным релизом обязательны проверка товарных знаков, домена и визуального сходства.
• Первая версия: web, English-first, invite-only, private worlds.
• Контент: 13+, без explicit‑материалов.
• OpenRouter оплачивает проект; пользователи не вводят собственные ключи.
• Оплаты нет — используются дневные, пользовательские и кампанийные лимиты.
• MVP полностью текстовый.
• Не входят: публичный каталог, marketplace, карты, изображения, TTS, видеогенерация, полноценный 5e combat, нативный desktop/mobile и пользовательские ruleset.
• После альфы приоритет определяется метриками: удержание кампаний, завершённые раунды, стоимость AI‑хода, частота ручных исправлений и качество памяти.