# Validator — проверка модов без запуска игры

Validator читает каждый мод запущенной игры — манифесты, файлы данных, сценарии, патчи сцен и исходники C# — и сообщает, что сломано или подозрительно: ссылку на предмет, сцену или фон, которые никто не объявляет, неизвестную команду сценария, неверный параметр, недостающую зависимость. Проверка запускается в фоне при каждом старте игры и пишет отчёт, так что опечатка находится раньше, чем игрок доберётся до строки с ней.

Проверяется то, что видно в файлах. Validator не играет в игру: сценарий, который он принял, всё равно может вести себя не так, как задумывал автор, а код, собирающий идентификаторы на ходу, проследить невозможно.

## Ошибка и её исправление

Строка сценария, выдающая игроку волчье мясо, с опечаткой в id предмета:

```scenario
scene: home_kitchen
priority: 0
---
action item.add id=food/wolf_meet count=1
end
```

После следующего запуска Cthangover в отчёте появляется:

```json
{
  "severity": "error",
  "code": "REF_NOT_FOUND",
  "message": "item 'food/wolf_meet' is referenced but never declared",
  "mod": "cthangover_game",
  "file": "scenarios/doc_validator_demo.scenario",
  "line": 4,
  "suggestion": "declare item 'food/wolf_meet' or fix the reference",
  "related": null
}
```

Мод, файл и строка указывают на ошибку. С `food/wolf_meat` проблема исчезает, а счётчик ошибок в сводке уменьшается на единицу (с 18 до 17 в этом прогоне).

## Как запустить и как читать отчёт

- Проверка стартует сама, когда входишь в игру, которая его содержит (Cthangover включает его в свой набор инструментов разработчика), после загрузки модов и идёт в фоновом потоке; игре она не мешает.
- В лог на каждый прогон пишется строка: `validator: started, 33 mod(s) queued`, затем итоги по ошибкам, предупреждениям и заметкам.
- Отчёт пишется в `user://validation/report.json` (в папке пользовательских данных игры). В нём сводка, проверенные моды с их версиями и контрольными суммами и список проблем.

У каждой проблемы есть:

- `severity` — `error` (что-то сломано), `warning` (похоже на ошибку) или `info` (стоит взглянуть, например предмет, на который никто не ссылается);
- `code` — род проблемы, например `REF_NOT_FOUND`, `JSON_PARSE_ERROR`, `SCHEMA_MISSING_FIELD`, `SCHEMA_UNKNOWN_PARAM`, `DECL_UNUSED`, `DYNAMIC_KEY`;
- `mod`, `file`, `line` — где исправлять; `suggestion` — что делать.

Заметки `DYNAMIC_KEY` означают, что ключ собирается во время выполнения, и Validator не может его проверить; ошибками они не являются.

## Что проверяется

Проверки идут в три фазы:

1. **Схема** — в `manifest.json` есть строки `id` и `version`; JSON-файлы разбираются.
2. **Контракты** — что мод объявляет и на что ссылается: сущности всех видов (персонажи, предметы, задания, навыки, рецепты, действия и виды, описанные схемами), команды и действия сценария с их параметрами, патчи сцен, свойства, которые читает и пишет код C#.
3. **Сверка** — у каждой ссылки есть объявление, `depends` покрывает то, что мод берёт у других, а объявления, которыми никто не пользуется, перечислены.

Сценарные действия и их параметры сверяются со схемами, которые поставляют моды (см. Schemas), по тем же правилам, что и в палитре команд.

## Настройки

На вкладке настроек мода в менеджере модов:

- **Enabled**, **Run on start** — отключают прогон;
- **Parse C#**, **Parse GDScript** (по умолчанию выключено, медленно), **Parse scenarios** — какие источники читать;
- **Write report**, **Report path** — куда пишется `report.json`;
- **Block mods on error** — есть в настройках, но в текущей версии ни на что не влияет: моды не блокируются никогда.

## Если что-то пошло не так

1. **Отчёта нет.** Игра закрылась до конца прогона (для Cthangover это около полуминуты) или выключен **Write report**.
2. **Много строк `DYNAMIC_KEY`.** Нормально для кода, который собирает ключи; это заметки.