# Resource Atlas — какой мод чьи ресурсы использует

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

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

## Как запустить

Атлас — инструментальный запуск: он строит отчёт и завершается.

```text
godot --path . -- --game=novel_template --with-mods=resource_atlas --resource-atlas --atlas-out=<folder>
godot --path . -- --resource-atlas --atlas-out=res://tests/artifacts/resource_atlas --with-test-suites
```

- С `--game=<id>` картируются моды этой игры (плюс оболочка); без него — все установленные моды.
- `--with-test-suites` добавляет к карте и тестовые наборы модов.
- В папку `--atlas-out` пишутся `report.md` (для чтения) и `report.json` (для инструментов); в лог идёт строка `atlas: N error(s), M warning(s)`, а при ошибках код выхода — 1.
- В тест-раннере это тесты: `resource_atlas` (все моды) и по одному на игру, например `resource_atlas_novel_template`.

Текст `report.md` написан по-русски.

## Пример связи между модами

У собственного мода шаблона новеллы, `my_novel_game`, своих картинок нет: его город, бар и дом берут фоны из `town_pack` — многоразового пака той же игры. В таблице связей отчёта это выглядит одной строкой:

```text
| `my_novel_game` | `town_pack` | yes | 3 | background | `bar/bar`, `home/vestibule`, `town/town_entry` |
```

Столбцы здесь такие: мод; мод, у которого он берёт ресурсы; есть ли тот в его `depends`; число использований, их виды и примеры. Строка верна, потому что `my_novel_game` объявляет `town_pack>=1` в своём `depends`.

Для этой страницы из манифеста на один запуск убрали зависимость. Атлас тогда упал с тремя ошибками — по одной на фон, каждая с файлом, который его использует:

```text
**Errors: 3** (mods: my_novel_game) · warnings: 0

### A foreign resource is used without a dependency in depends

- `my_novel_game` → `town_pack`: background `bar/bar` — uses a resource of the mod town_pack (data) that is not in depends — add the dependency or move the resource. `scenes/my_novel_bar.json`
```

С возвращённой зависимостью в отчёте снова нет ошибок.

Почему это важно: без `depends` ничто не заставит игру загрузить `town_pack` вместе с модом шаблона. Игрок, поставивший только `my_novel_game`, получил бы сцены без фонов.

## Что внутри отчёта

- **Ошибки** — чужой ресурс используется без зависимости; один ключ дают моды, не связанные `depends`; патч чужого ресурса без зависимости.
- **Связи между модами** — кто у кого что берёт, объявлено ли это, сколько и каких видов.
- **Переопределения** — ключи, которые кладут несколько модов, и какой из них побеждает.
- **Патчи чужих ресурсов** — патчи сцен и сущностей, с указанием пропатченного мода.
- **Предупреждения** — ключи, которых не даёт ни один загруженный мод.
- **Сводка по модам** и **порядок загрузки**.

Сопоставление ключей повторяет правила игры: текстуры — по имени файла; звуки, музыка, шейдеры и сцены — по пути внутри группы; сущности — по виду и идентификатору; переводы — по языку и ключу.

## Как исправить найденное

1. **Ресурс используется без зависимости.** Добавьте владельца в `depends`, перенесите ресурс в мод, который им пользуется, или дайте своей копии собственный ключ.
2. **Один ключ в несвязанных модах.** Если один должен заменять другой, заменяющий мод обязан зависеть от владельца; иначе переименуйте один из них.
3. **Ключ, который никто не даёт.** Либо опечатка, либо дающий мод не входит в эту игру.