mod_resource_atlas/docs/ru.md

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

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

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

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

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

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 — многоразового пака той же игры. В таблице связей отчёта это выглядит одной строкой:

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

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

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

**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. Ключ, который никто не даёт. Либо опечатка, либо дающий мод не входит в эту игру.