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.