# 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](https://fables.gg/), [описание их системы памяти](https://help.fables.gg/articles/2838157-memories).

## 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](https://www.dndbeyond.com/srd).

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

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

- неизменяемый журнал действий и результатов;
- текущую сцену и активные сущности;
- структурированное состояние персонажей, 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](https://openrouter.ai/docs/guides/features/tool-calling), [structured outputs](https://openrouter.ai/docs/guides/features/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‑хода, частота ручных исправлений и качество памяти.