# Vanguard Re:Master

Фанатский ремастер Cardfight!! Vanguard базовой эры (2011): формат `Classic`, сет BT01 и два триал-дека TD01/TD02.

> Fan-made project. Not affiliated with Bushiroad. All card names and art belong to their respective owners.

## Статус

| Блок | Состояние |
|---|---|
| Документация и решения | готово |
| Каталог карт (94 / 124 принта) | готово |
| Контент-пайплайн и валидатор | готово |
| Игровое ядро (правила) | каркас: фазы, райд, призыв, бой, драйв, урон |
| Протокол и контракты (`docs/protocol.md`, `Vanguard.Shared`) | готово |
| Сервер: матч по сети, матчмейкинг, реконнект | готово |
| PostgreSQL (матчи), Redis (тикеты, очередь), Docker | готово |
| Мета-API: JWT, коллекция, колоды, магазин, история, реплеи | готово |
| CI (Forgejo Actions) | готово: `ci.yml` проходит на `home-runner` |
| EF-миграции | готово (`InitialCreate`) |
| Orleans | готово: silo + `MatchActorGrain`, включается `Orleans:Enabled` |
| Клиент | Unity 6.6: логин, онбординг, коллекция, колоды, очередь, gray-box бой |
| Лаунчер | не начато |

## Требования

- **.NET SDK 10** (LTS). Версия зафиксирована в `global.json`.
- **Python 3** — только для переимпорта карт из первоисточника.

## Быстрый старт

```powershell
# проверить целостность контента
dotnet run --project server/src/Vanguard.Cli -- validate

# сводка по кланам, триггерам и редкостям
dotnet run --project server/src/Vanguard.Cli -- stats

# 1000 партий случайного бота с проверкой инвариантов
dotnet run --project server/src/Vanguard.Cli -- stress 1000

# тесты
dotnet test server/Vanguard.slnx
```

Запуск игрового сервера:

```powershell
dotnet run --project server/src/Vanguard.Server --urls http://localhost:5080
# проверка: http://localhost:5080/health
```

Orleans по умолчанию выключен; `Orleans__Enabled=true` включает silo в том же
процессе. В `docker-compose.yml` он уже включён; для локального запуска без
Orleans ничего дополнительно настраивать не нужно. Состояние соединений
остаётся в процессе, поэтому несколько реплик сервера пока не поддерживаются.

Контейнер: `docker compose up --build`, затем `http://localhost:8080/health`.
Порт задаётся в `.env` (`VANGUARD_PORT`, `VANGUARD_WS_URL`); стек включает
PostgreSQL и Redis (AOF). HTTP-контракт очереди и тикетов — `docs/server-api.md`.

Ожидаемый вывод валидатора:

```
Карт: 94   Принтов: 124

OK: ошибок 0, предупреждений 0
```

## Структура

```
/server/src/Vanguard.Rules        ядро правил: карты, колоды, состояние игры
/server/src/Vanguard.Content      загрузка и проверка YAML-контента
/server/src/Vanguard.Shared       сетевые контракты (netstandard2.1 для Unity + net10.0)
/server/src/Vanguard.Server       ASP.NET Core: WebSocket, мета-API, магазин, матчи
  /Auth                           JWT, register/login/refresh, BCrypt
  /Meta                           коллекция, колоды, экономика, история, реплеи
  /Storage                        PostgreSQL-снапшоты и восстановление матчей
  /Matchmaking                    очередь, MMR, Redis-хранилище очереди
  /Tickets                        тикеты: память или Redis
/server/src/Vanguard.Cli          консольные команды
/server/tests                     тесты правил, контрактов и сервера (включая E2E)
/content/sets                     карты в YAML
/content/trial-decks.yaml         две триал-деки
/content/pack_odds.yaml           веса бустера
/content/keywords.yaml            ключевые слова и иконки
/content/translations/ru.yaml     русские тексты
/tools                            импорт и сид переводов
/docs                             протокол, API, правила перевода
/docker-compose.yml               PostgreSQL, Redis и сервер
```

`Vanguard.Rules` — чистая библиотека без Orleans, БД и сети. Это позволяет прогонять
матчи в консоли и проверять правила до появления клиента.

## Контент

Первоисточник — официальный карт-лист `en.cf-vanguard.com`; триггеры и редкости
выгружены из вики. Пересобрать YAML:

```powershell
python tools/import_cards.py
```

Валидатор проверяет инварианты, которые легко нарушить вручную:

- у grade 0 щит 5000 **только** у Draw-триггера, иначе 10000;
- Sentinel всегда со щитом 0;
- параллельный принт (`BT01/S01`…`S12`) ссылается на существующий базовый принт той же карты;
- в колоде ровно 50 карт, ≤4 копий по имени (а не по принту), ≤4 Sentinel, ≤4 Heal.

## Тексты карт и иконки

Ключевые слова (`[AUTO]`, `[Counter-Blast 3]`, `(VC/RC)`, `<Kagero>`) заменяются
на иконки при отрисовке. Чтобы перевод не ломал разметку, тексты хранятся в виде
**шаблонов с токенами**:

```
{auto}:{cb:2} When this unit is placed on {vc}, you may pay the cost...
```

Список токенов и их иконок — `content/keywords.yaml`.
Русские тексты — `content/translations/ru.yaml`: заполняется только `textRu`.
Поле `nameRu` существует, но пока содержит английское название — на случай,
если позже решим переименовать карты.
Правила перевода и спорные термины — `docs/translation-rules.md`.

Черновой перевод всех 66 текстов уже залит; его правит человек, после чего
правила уточняются под фактические правки.

```powershell
# создать файл переводов или обновить шаблоны, сохранив введённые переводы
dotnet run --project server/src/Vanguard.Cli -- translations build

# проверить заполнение и целостность токенов
dotnet run --project server/src/Vanguard.Cli -- translations check
```

Проверка ловит: незаполненные тексты, потерянные или лишние токены,
токены, которых нет в справочнике. Карты без эффекта считаются готовыми
сразу — им переводить нечего.

## Документация

- `plan.md` — исходный дизайн-документ.
- `DEVELOPMENT_CHECKLIST.md` — решения, механики, экономика, риски.
- `IMPLEMENTATION_CHECKLIST.md` — план реализации по блокам и гейтам.
- `docs/HANDOFF.md` — состояние на конец сессии и порядок следующих шагов.
- `docs/protocol.md` — протокол матча: кадры, интенты, события, таймеры, реконнект.
- `docs/server-api.md` — HTTP API: JWT, коллекция, колоды, магазин, очередь,
  история и реплеи.
- `content/cards-mvp.md` — каталог карт с разбором состава сетов.