airdef/docs/REPO-MAP.md

# Карта репозитория

Что здесь что: исходники, сгенерированное, архив. Порядок сборки и установки — в `README.md` и `docs/INSTALL.md`.

## Исходники (правим руками)

| Путь | Что это |
|---|---|
| `airdef-mod/src/`, `airdef-mod/shaders/` | Мод на Rust (WASM) для форка Horizon |
| `airdef-core/` | SDK-free сборка того же ядра из `airdef-mod/src/sim/`; не отдельная копия исходников |
| `airdef-mod/src/sim/battery.rs`, `launch.rs`, `logistics.rs` | Конфигурация батареи, физические ячейки/крышки и снабжение |
| `docs/CODEX-HANDOFF.md`, `docs/IMPLEMENTATION-STATUS.md` | Техническая передача разработки и фактический статус задач |
| `airdef-mod/Cargo.toml`, `horizon-mod.toml` | Сборка мода |
| `airdef-mod/tests/`, `airdef-mod/examples/` | Тесты и примеры |
| `airdef-mod/NOTES-terrain-guidance.md` | Рабочие заметки по рельефу |
| `horizon/`, `.gitmodules` | Закреплённый сабмодуль отдельного форка Horizon |
| `tools/airdef.py` | Сборка мода и установка в папку игры |
| `tools/gen_models.py`, `tools/gen_tex.py`, `tools/gen_sounds.py` | Генераторы контента (см. ниже) |
| `tools/acoustics_check.py`, `tools/hd_bench.py` | Проверочные скрипты |
| `docs/` | Документация (этот файл, `INSTALL.md`, `ACOUSTICS.md`, `HD-RENDERER.md`) |
| `install.sh`, `play.sh`, `dist/` | Установка и запуск |
| `run-home/`, `run-home-bench/`, `run-home-smoke/` | Тестовые игровые папки, не часть мода |
| `screenshots/` | Скриншоты |

## Сгенерировано (не правим руками)

`tools/gen_models.py` создаёт:

- `airdef-mod/assets/airdef/{blockstates,models,items,lang,textures}/`
- `airdef-mod/data/airdef/horizon/`

Список этих файлов с sha256 лежит в `airdef-mod/generated-manifest.txt`. Генератор пишет во временный каталог, проверяет набор (ссылки моделей, blockstate и текстур; JSON; PNG; координаты элементов; парность lang) и только потом переносит файлы. При ошибке проверки ничего не записывается. Файл, который правили вручную или который занимает путь генерируемого, останавливает запуск (`КОНФЛИКТ`).

Команды:

- `python3 -m pip install -r tools/requirements.txt` — зависимости генератора (закреплён Pillow).
- `python3 tools/gen_models.py` — перегенерировать.
- `python3 tools/gen_models.py --check` — только сравнить, выход 1 при различиях.

`tools/gen_sounds.py` создаёт `airdef-mod/assets/airdef/sounds/*.ogg` и `sounds.json`. Этот генератор не использует manifest и не входит в проверку `gen_models.py`.

## Архив: `legacy/`

Первая версия мода: датапак на командах (`legacy/airdef-datapack/`) и контент-мод (`legacy/airdef-content/`) с генератором `legacy/gen_content.py`. Ничего из текущей сборки на него не ссылается: ни скрипты в `tools/`, ни `install.sh`, ни `Cargo.toml`, ни исходники мода. Не собирается и не устанавливается. Оставлен как история. Не редактировать и не удалять без отдельного решения.

`legacy/airdef-content/data/` сейчас не отслеживается git и не входит в эту карту.

## Авторские и сгенерированные ресурсы

- `tools/gen_models.py` генерирует геометрию моделей и управляет сборкой набора.
- `tools/airdef_assets/registry.py` создаёт blockstate/item registry, локализацию и data JSON.
- `tools/airdef_assets/bounds.py` экспортирует габариты итоговых моделей для headless-навигации; authored overrides входят в расчёт.
- `tools/gen_tex.py` отвечает за вывод процедурных текстур и иконок; переиспользуемые примитивы палитры также находятся здесь.
- `tools/airdef_assets/texture_catalog.py` связывает стабильную палитру и процедурные функции с текстурами моделей, не смешивая каталог с геометрией.
- `tools/airdef_assets/icons.py` содержит каталог предметов и чистую функцию рендера иконки с явными параметрами `(name, color, seed)`.
- `tools/airdef_assets/pipeline.py` проверяет manifest, рассчитывает безопасный план обновления и откатывает записи при исключении.
- `airdef-mod/source-assets/assets/airdef/` — источник авторских переопределений. Генератор объединяет его с процедурными ресурсами во временном дереве, проверяет ссылки/JSON/PNG, затем устанавливает runtime-файлы.
- `airdef-mod/assets/` и `airdef-mod/data/` — упакованные generated output. Не редактируйте их вручную; добавляйте авторские исходники в `source-assets`.
- `airdef-mod/generated-manifest.txt` хранит SHA-256 только для управляемого результата. Неизменённые старые outputs можно заменить или удалить; посторонние и вручную правленные файлы блокируют конфликтующий запуск.
- `python3 tools/test_gen_assets.py` проверяет manifest, защиту ручных файлов, откат при ошибке записи, детерминизм и полный цикл authored icon override/validation.

`airdef-mod/src/sim/generated_bounds.rs` также управляется manifest: это данные геометрии, а не файл для ручного редактирования. Пилотный арт и сравнения — в `docs/MODEL-PILOTS.md`.