Add mod documentation in seven languages

docs/en.md

@@ -0,0 +1,62 @@
+# Resource Atlas — which mod uses whose resources
+
+The Resource Atlas maps how the mods of a game use each other's resources: backgrounds, sounds, music, shaders, scenes, textures, entities, translation keys, scenario actions and patches. For every use it checks that the mod which takes the resource depends on the mod which gives it. It also finds the same key shipped by mods that do not depend on each other — then the winner depends on load order, which is not defined — and keys that no mod provides.
+
+It builds on the Validator's graph of declarations and references and adds what the Validator does not follow: texture, sound and shader keys, translation keys and keys written as literals in C# code.
+
+## Running it
+
+The atlas is a tool run: it builds the report and quits.
+
+```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
+```
+
+- With `--game=<id>` it maps the mods of that game (plus the shell); without it, every installed mod.
+- `--with-test-suites` also maps the test suites of the mods.
+- It writes `report.md` (to read) and `report.json` (for tools) into the `--atlas-out` folder, logs `atlas: N error(s), M warning(s)` and exits with 1 when there are errors.
+- The test runner has it as tests: `resource_atlas` (all mods) and one per game, such as `resource_atlas_novel_template`.
+
+The text of `report.md` is written in Russian.
+
+## A cross-mod example
+
+The novel template's own mod, `my_novel_game`, has no pictures of its own: its town, bar and home use backgrounds of `town_pack`, a reusable pack of the same game. The report's table of links shows this as one row:
+
+```text
+| `my_novel_game` | `town_pack` | yes | 3 | background | `bar/bar`, `home/vestibule`, `town/town_entry` |
+```
+
+The columns are: the mod, the mod it takes resources from, whether that mod is in its `depends`, the number of uses, their kinds and examples. The row is correct because `my_novel_game` declares `town_pack>=1` in its `depends`.
+
+For this page the dependency was removed from the manifest for one run. The atlas then failed with three errors, one per background, each with the file that uses it:
+
+```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`
+```
+
+With the dependency back, the report has no errors again.
+
+Why it matters: without `depends`, nothing makes the game load `town_pack` with the template's mod. A player who installs only `my_novel_game` would get scenes without backgrounds.
+
+## What the report contains
+
+- **Errors** — a foreign resource used without a dependency; one key provided by mods not linked by `depends`; a patch of a foreign resource without a dependency.
+- **Links between mods** — who takes whose resources, whether it is declared, how many and of which kinds.
+- **Overrides** — keys shipped by several mods and which one wins.
+- **Patches of foreign resources** — scene and entity patches, with the patched mod.
+- **Warnings** — keys no loaded mod provides.
+- **Summary by mod** and the **load order**.
+
+How keys are matched follows the game: textures by file name, sounds, music, shaders and scenes by their path in the group, entities by kind and id, translations by language and key.
+
+## Fixing what it finds
+
+1. **A resource used without a dependency.** Add the owner to `depends`, or move the resource into the mod that uses it, or give your copy its own key.
+2. **The same key in unrelated mods.** If one should replace the other, the replacing mod must depend on the owner; otherwise rename one of them.
+3. **A key nobody provides.** A typo, or the providing mod is not part of this game.

docs/es.md

@@ -0,0 +1,62 @@
+# Resource Atlas — qué mod usa los recursos de cuál
+
+El Atlas de recursos traza cómo los mods de un juego usan los recursos de los demás: fondos, sonidos, música, shaders, escenas, texturas, entidades, claves de traducción, acciones de escenario y parches. Para cada uso comprueba que el mod que toma el recurso dependa del que lo da. También encuentra la misma clave servida por mods que no se dependen entre sí —entonces el ganador depende del orden de carga, que no está definido—, y claves que nadie proporciona.
+
+Se apoya en el grafo de declaraciones y referencias del Validator y añade lo que este no sigue: claves de texturas, sonidos y shaders, claves de traducción y claves escritas como literales en código C#.
+
+## Cómo se ejecuta
+
+El atlas es una ejecución de herramienta: construye el informe y sale.
+
+```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
+```
+
+- Con `--game=<id>` mapea los mods de ese juego (más la shell); sin él, todos los mods instalados.
+- `--with-test-suites` mapea también los conjuntos de pruebas de los mods.
+- Escribe `report.md` (para leer) y `report.json` (para herramientas) en la carpeta `--atlas-out`, registra `atlas: N error(s), M warning(s)` y sale con código 1 si hay errores.
+- El test runner lo tiene como pruebas: `resource_atlas` (todos los mods) y una por juego, como `resource_atlas_novel_template`.
+
+El texto de `report.md` está escrito en ruso.
+
+## Un ejemplo entre mods
+
+El mod propio de la plantilla de novela, `my_novel_game`, no tiene imágenes suyas: su ciudad, su bar y su casa usan fondos de `town_pack`, un paquete reutilizable del mismo juego. La tabla de enlaces del informe lo muestra en una fila:
+
+```text
+| `my_novel_game` | `town_pack` | yes | 3 | background | `bar/bar`, `home/vestibule`, `town/town_entry` |
+```
+
+Las columnas son: el mod, el mod del que toma recursos, si ese mod está en su `depends`, el número de usos, sus clases y ejemplos. La fila es correcta porque `my_novel_game` declara `town_pack>=1` en su `depends`.
+
+Para esta página se quitó la dependencia del manifiesto durante una ejecución. El atlas falló entonces con tres errores, uno por fondo, cada uno con el archivo que lo usa:
+
+```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`
+```
+
+Con la dependencia de vuelta, el informe vuelve a quedarse sin errores.
+
+Por qué importa: sin `depends`, nada obliga al juego a cargar `town_pack` junto con el mod de la plantilla. Un jugador que instale solo `my_novel_game` vería escenas sin fondos.
+
+## Qué contiene el informe
+
+- **Errores** — un recurso ajeno usado sin dependencia; una clave servida por mods no enlazados por `depends`; un parche de un recurso ajeno sin dependencia.
+- **Enlaces entre mods** — quién toma los recursos de quién, si está declarado, cuántos y de qué clases.
+- **Sustituciones** — claves servidas por varios mods y cuál gana.
+- **Parches de recursos ajenos** — parches de escenas y entidades, con el mod parcheado.
+- **Advertencias** — claves que ningún mod cargado proporciona.
+- **Resumen por mod** y el **orden de carga**.
+
+El emparejamiento de claves sigue las reglas del juego: texturas por nombre de archivo; sonidos, música, shaders y escenas por su ruta dentro del grupo; entidades por clase e id; traducciones por idioma y clave.
+
+## Cómo arreglar lo que encuentra
+
+1. **Un recurso usado sin dependencia.** Añade el propietario a `depends`, mueve el recurso al mod que lo usa o dale a tu copia su propia clave.
+2. **La misma clave en mods sin relación.** Si uno debe sustituir al otro, el que sustituye debe depender del propietario; si no, renombra uno de los dos.
+3. **Una clave que nadie proporciona.** Una errata, o el mod que la da no forma parte de este juego.

docs/ja.md

@@ -0,0 +1,62 @@
+# Resource Atlas — どの MOD がどの MOD のリソースを使っているか
+
+Resource Atlas は、ゲーム内の MOD 同士が互いのリソースをどう使っているかを地図にします。対象は背景、効果音、音楽、シェーダー、シーン、テクスチャ、エンティティ、翻訳キー、シナリオアクション、パッチです。利用が一つあるごとに、リソースを取る側の MOD が与える側の MOD に依存しているかを検査します。さらに、互いに依存していない MOD が同じキーを提供している場合——そのとき勝者は未定義の読み込み順で決まります——や、どの MOD も提供していないキーも見つけます。
+
+土台は Validator の宣言と参照のグラフで、そこに 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>` を付けるとそのゲームの MOD（シェルも含む）をマップし、付けない場合はインストール済みの全 MOD を対象にします。
+- `--with-test-suites` を付けると、MOD のテストスイートもマップします。
+- `--atlas-out` フォルダーに `report.md`（読む用）と `report.json`（ツール用）を書き込み、`atlas: N error(s), M warning(s)` をログに出し、エラーがあれば終了コード 1 で終わります。
+- テストランナーでは次のテストとして登録されています。`resource_atlas`（全 MOD）と、ゲームごとの `resource_atlas_novel_template` など。
+
+`report.md` の本文はロシア語で書かれています。
+
+## MOD をまたいだ例
+
+小説テンプレート自前の MOD である `my_novel_game` には、独自の画像がありません。その町・バー・家は、同じゲームの再利用可能なパック `town_pack` の背景を使います。レポートのリンク表では、これが 1 行として現れます:
+
+```text
+| `my_novel_game` | `town_pack` | yes | 3 | background | `bar/bar`, `home/vestibule`, `town/town_entry` |
+```
+
+列は左から、その MOD、リソースを取る相手の MOD、相手が自分の `depends` に入っているかどうか、利用数とその種類、そして例です。この行が正しいのは、`my_novel_game` が自分の `depends` で `town_pack>=1` を宣言しているからです。
+
+このページのため、1 回の実行でのみマニフェストからこの依存を取り除きました。するとアトラスは 3 つのエラーで失敗しました。背景ごとに 1 つずつ、それぞれ使っているファイル付きです:
+
+```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` がなければ、テンプレートの MOD と一緒に `town_pack` を読み込ませるものは何もありません。`my_novel_game` だけをインストールしたプレイヤーは、背景のないシーンを見ることになります。
+
+## レポートの中身
+
+- **エラー** — 依存関係なしに他 MOD のリソースを使っている。`depends` でつながっていない MOD が同じキーを提供している。依存関係なしに他 MOD のリソースへパッチを当てている。
+- **MOD 間のリンク** — 誰が誰のリソースを取るか、それが宣言されているか、件数と種類。
+- **上書き** — 複数の MOD が提供しているキーと、どれが勝つか。
+- **他 MOD リソースへのパッチ** — シーンとエンティティのパッチと、パッチ先の MOD。
+- **警告** — 読み込まれたどの MOD も提供していないキー。
+- **MOD ごとの集計**と**読み込み順**。
+
+キーの対応づけはゲームのルールに従います。テクスチャはファイル名、効果音・音楽・シェーダー・シーンはグループ内のパス、エンティティは種類と id、翻訳は言語とキーです。
+
+## 見つかった問題の直し方
+
+1. **依存関係なしに使われているリソース。** 所有者を `depends` に足すか、リソースを使っている側の MOD へ移すか、自分のコピーに固有のキーを与えます。
+2. **無関係な MOD に同じキー。** 一方がもう一方を置き換えるはずなら、置き換える側が所有者に依存しなければなりません。そうでなければ、どちらかの名前を変えます。
+3. **誰も提供していないキー。** タイプミスか、提供する MOD がこのゲームに含まれていないかです。

docs/ko.md

@@ -0,0 +1,62 @@
+# Resource Atlas — 어떤 모드가 누구의 리소스를 쓰는가
+
+Resource Atlas는 게임의 모드들이 서로의 리소스를 어떻게 사용하는지 지도로 보여 줍니다. 대상은 배경, 효과음, 음악, 셰이더, 씬, 텍스처, 엔티티, 번역 키, 시나리오 액션, 패치입니다. 사용이 하나 있을 때마다 리소스를 가져오는 모드가 제공하는 모드에 의존하는지 검사합니다. 또한 서로 의존하지 않는 모드들이 같은 키를 제공하는 경우—이때 승자는 정해지지 않은 로드 순서에 달려 있습니다—와 어느 모드도 제공하지 않는 키도 찾아 냅니다.
+
+Validator의 선언·참조 그래프를 기반으로 하며, 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`이 자신의 `depends`에 `town_pack>=1`을 선언하기 때문입니다.
+
+이 페이지를 위해 한 번의 실행에서만 매니페스트에서 이 의존성을 제거했습니다. 그러자 아틀라스는 배경마다 하나씩, 각각 사용하는 파일과 함께 세 개의 오류로 실패했습니다:
+
+```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`로 연결되지 않은 모드들이 같은 키를 제공함. 의존성 없이 다른 모드의 리소스를 패치함.
+- **모드 간 링크** — 누가 누구의 리소스를 가져오는지, 선언되어 있는지, 몇 개이며 어떤 종류인지.
+- **재정의** — 여러 모드가 제공하는 키와 어느 쪽이 이기는지.
+- **다른 모드 리소스에 대한 패치** — 씬·엔티티 패치와 패치된 모드.
+- **경고** — 로드된 어느 모드도 제공하지 않는 키.
+- **모드별 요약**과 **로드 순서**.
+
+키 매칭은 게임의 규칙을 따릅니다. 텍스처는 파일 이름으로, 효과음·음악·셰이더·씬은 그룹 안 경로로, 엔티티는 종류와 id로, 번역은 언어와 키로 맞춥니다.
+
+## 발견한 것 고치기
+
+1. **의존성 없이 사용되는 리소스.** 소유자를 `depends`에 추가하거나, 리소스를 그것을 사용하는 모드로 옮기거나, 여러분의 사본에 고유한 키를 주세요.
+2. **관련 없는 모드에 같은 키.** 한쪽이 다른 쪽을 대체해야 한다면 대체하는 모드가 소유자에 의존해야 합니다. 그렇지 않다면 둘 중 하나의 이름을 바꾸세요.
+3. **아무도 제공하지 않는 키.** 오타이거나, 제공하는 모드가 이 게임에 속하지 않는 것입니다.

docs/ru.md

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

docs/vi.md

@@ -0,0 +1,62 @@
+# Resource Atlas — mod nào dùng tài nguyên của mod nào
+
+Resource Atlas vẽ ra cách các mod của một game dùng tài nguyên của nhau: background, âm thanh, nhạc, shader, cảnh, texture, entity, khóa dịch, hành động kịch bản và các bản vá. Với mỗi lần sử dụng, nó kiểm tra rằng mod lấy tài nguyên có phụ thuộc vào mod cho không. Nó cũng tìm ra trường hợp nhiều mod không phụ thuộc lẫn nhau lại cung cấp cùng một khóa — khi đó bên thắng phụ thuộc vào thứ tự tải, vốn không được định nghĩa — và những khóa không mod nào cung cấp.
+
+Nó xây trên đồ thị khai báo và tham chiếu của Validator, cộng thêm những gì Validator không theo dõi: khóa texture, âm thanh và shader, khóa dịch, và các khóa được viết dạng literal trong mã C#.
+
+## Cách chạy
+
+Atlas là một lần chạy công cụ: nó tạo báo cáo rồi thoát.
+
+```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
+```
+
+- Có `--game=<id>` thì nó vẽ các mod của game đó (cộng cả shell); không có thì vẽ mọi mod đã cài.
+- `--with-test-suites` vẽ thêm cả các bộ kiểm thử của mod.
+- Nó ghi `report.md` (để đọc) và `report.json` (cho công cụ) vào thư mục `--atlas-out`, ghi log `atlas: N error(s), M warning(s)` và thoát với mã 1 khi có lỗi.
+- Trong test runner, nó là các phép kiểm thử: `resource_atlas` (mọi mod) và mỗi game một phép, ví dụ `resource_atlas_novel_template`.
+
+Phần chữ của `report.md` được viết bằng tiếng Nga.
+
+## Một ví dụ giữa các mod
+
+Mod riêng của bản mẫu tiểu thuyết, `my_novel_game`, không có hình ảnh của riêng nó: thị trấn, quán bar và ngôi nhà của nó dùng background của `town_pack` — một gói tái sử dụng của cùng game. Bảng liên kết trong báo cáo hiển thị điều này thành một dòng:
+
+```text
+| `my_novel_game` | `town_pack` | yes | 3 | background | `bar/bar`, `home/vestibule`, `town/town_entry` |
+```
+
+Các cột lần lượt là: mod, mod mà nó lấy tài nguyên, mod đó có nằm trong `depends` của nó không, số lần dùng, các loại và ví dụ. Dòng này đúng vì `my_novel_game` khai báo `town_pack>=1` trong `depends` của mình.
+
+Cho trang này, người ta đã gỡ phần phụ thuộc khỏi manifest trong đúng một lần chạy. Atlas lập tức thất bại với ba lỗi — mỗi background một lỗi, kèm theo tệp đang dùng nó:
+
+```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`
+```
+
+Có lại phần phụ thuộc, báo cáo lại không còn lỗi.
+
+Vì sao điều này quan trọng: không có `depends`, không gì buộc game tải `town_pack` cùng với mod của bản mẫu. Người chơi chỉ cài `my_novel_game` sẽ thấy những cảnh không có background.
+
+## Báo cáo chứa gì
+
+- **Lỗi** — dùng tài nguyên của người khác mà không có phụ thuộc; nhiều mod không liên kết bằng `depends` lại cung cấp cùng một khóa; vá tài nguyên của người khác mà không có phụ thuộc.
+- **Liên kết giữa các mod** — ai lấy tài nguyên của ai, có được khai báo không, bao nhiêu và thuộc loại nào.
+- **Ghi đè** — những khóa do nhiều mod cung cấp và bên nào thắng.
+- **Vá tài nguyên của mod khác** — các bản vá cảnh và entity, kèm mod bị vá.
+- **Cảnh báo** — những khóa không mod nào đang tải cung cấp.
+- **Tổng kết theo mod** và **thứ tự tải**.
+
+Cách khớp khóa theo đúng luật của game: texture theo tên tệp; âm thanh, nhạc, shader và cảnh theo đường dẫn trong nhóm; entity theo loại và id; bản dịch theo ngôn ngữ và khóa.
+
+## Sửa những gì nó tìm thấy
+
+1. **Tài nguyên được dùng mà không có phụ thuộc.** Thêm chủ sở hữu vào `depends`, chuyển tài nguyên sang mod đang dùng nó, hoặc cho bản sao của bạn một khóa riêng.
+2. **Cùng một khóa ở những mod không liên quan.** Nếu bên này phải thay thế bên kia thì bên thay thế phải phụ thuộc vào chủ sở hữu; nếu không, hãy đổi tên một trong hai.
+3. **Một khóa không ai cung cấp.** Hoặc là lỗi đánh máy, hoặc mod cung cấp nó không thuộc game này.

docs/zh.md

@@ -0,0 +1,62 @@
+# Resource Atlas — 哪个模组在用谁的资源
+
+资源图谱描绘游戏中各模组如何使用彼此的资源：背景、音效、音乐、着色器、场景、纹理、实体、翻译键、剧情动作和补丁。对每一次使用，它都会检查取用资源的模组是否依赖提供资源的模组。它还会找出互不依赖的模组提供同一个键的情况——此时谁胜出取决于并未定义的加载顺序——以及没有任何模组提供的键。
+
+它建立在 Validator 的声明与引用图之上，并补充了 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` 会把各模组的测试套件也纳入映射。
+- 它会把 `report.md`（供阅读）和 `report.json`（供工具使用）写进 `--atlas-out` 文件夹，在日志里输出 `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` 在自己的 `depends` 中声明了 `town_pack>=1`。
+
+为了这一页，我们在一次运行前从清单里移除了这条依赖。图谱随即报出三个错误——每个背景一条，各自指出使用它的文件：
+
+```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` 关联）的模组提供了同一个键；未声明依赖就给他人资源打补丁。
+- **模组之间的关联** — 谁在用谁的资源、是否已声明、数量多少、属于哪些种类。
+- **覆盖** — 由多个模组提供的键，以及哪一个胜出。
+- **对他人资源的补丁** — 场景和实体补丁，并标出被打补丁的模组。
+- **警告** — 没有任何模组提供的键。
+- **按模组汇总**和**加载顺序**。
+
+键的匹配方式沿用游戏的规则：纹理按文件名；音效、音乐、着色器和场景按其在组内的路径；实体按种类和 id；翻译按语言和键。
+
+## 如何修复发现的问题
+
+1. **资源在未声明依赖的情况下被使用。** 把所有者加进 `depends`，把资源移进使用它的模组，或者给你的副本一个自己的键。
+2. **同一个键出现在互不相关的模组里。** 如果其中一个应当替换另一个，替换方必须依赖所有者；否则请重命名其中一个。
+3. **没有人提供的键。** 要么是笔误，要么是提供它的模组不属于这个游戏。