Графика мода: постройки и свет

Это руководство для тех, кто делает мод с новой графикой построек на карте. Оно идёт от копии игры до мода, который игроки ставят через окно Карты и моды. Установка модов описана в Установке модов и патчей, а юниты и предметы меняются так, как написано в Своих спрайтах.

1. Что понадобится

Копия игры. Работайте на копии папки игры, а не на самой игре: «Обновить игру из архива…» заменяет файлы в папке, которую использует Razdor. Базой для мода служит Community Update.
Редактор картинок с прозрачностью, который сохраняет PNG с альфа-каналом.
Программа, которая записывает Graphics/Objects/Objects.ugs. Razdor этот файл читает, но в проекте нет инструмента, который его пишет. Спросите на Discord-сервере сообщества, чем сейчас правят этот файл.
Видеокарта NVIDIA с CUDA и Python, только если вы готовите данные для Razdor сами (шаг 4, вариант Б). Обычному моддеру это не нужно.

2. Заменить спрайт

Постройки на карте лежат в одном файле: Graphics/Objects/Objects.ugs в папке игры. В нём все объекты карты; постройки лежат в его разделе 1 (раздел — это группа записей подряд). Юниты и предметы в этом файле не лежат.

Скопируйте папку игры для мода.
Замените картинку постройки в Objects.ugs своей. Оставьте её размер тем же: данные о постройке проверяют размер, и готовые данные не подходят картинке другого размера. Не меняйте порядок записей в файле.
Прозрачность в файле хранится по 4 бита на канал, поэтому её значения кратны 17. Razdor считает пиксели с прозрачностью 204 и выше частью постройки, а пиксели с прозрачностью от 153 до 187 тенью, которая не входит ни в один кусок. Нарисуйте тень полупрозрачной в этом диапазоне, а стену и крышу непрозрачными.

3. Проверить в 2.5D, от третьего и от первого лица

Откройте «Настройки звука, графики и игры», вкладка «Карта».

Поставьте «Качество графики» на «Своё». Значение «Оригинал» выключает освещение, живую карту, погоду, туман и живую воду разом, и со светом постройку не увидеть.
«Вид карты» по нажатиям переключает: «Плоский» → «2.5D» → «От третьего лица» → «От первого лица» → снова «Плоский».
В 2.5D постройка стоит одной картинкой, как и в плоском виде. Проверьте, что она стоит на своём месте и не обрезана. Клавиши Q и E поворачивают вид на 45°: смотрите здание со всех сторон.
От третьего лица камера стоит за спиной героя. Строки «Наклон камеры» (от 5° до 60°), «Высота камеры», «Угол обзора» и «Камера поворачивается за героем» задают кадр.
От первого лица камера стоит у глаз героя. Строки «Высота камеры» (высота глаз, 0.70 по умолчанию), «Наклон камеры» (от −5° вверх до 30°), «Даль», «Начало изгиба» и «Сила изгиба» показываются в обоих видах от первого лица.
Смотрите постройку вблизи и вдали: в видах от первого лица земля загибается, и постройка может выглядеть иначе, чем в 2.5D.

4. Постройки на земле (сейчас выключено)

Сейчас постройки рисуются целыми картинками: разрезание на куски и постановка на землю выключены по умолчанию. Этот раздел описывает путь разработки: строка модели глубины в настройках скрыта, пока куски не включены переменной RAZDOR_BUILDING_CARDS=1.

Есть два пути. Игрок получает путь А. Путь Б делают сопровождающие проекта.

А. Модель глубины на компьютере игрока

Так Razdor ставит на землю постройки модов, у которых нет готовых данных.

Пока куски выключены (по умолчанию), строки нет и модель не запускается. Когда куски включены, в «Настройках» на вкладке «Карта» появляется строка «Модель глубины для модов»: она видна, когда вид карты 2.5D, от третьего или от первого лица и на карте есть постройки без данных.
Нажмите «Скачать (50 МБ)». Модель Depth Anything V2 Small (Apache-2.0) скачивается один раз и работает на вашем устройстве. Строка покажет «Загрузка N%». Если загрузка не удалась, строка напишет «Не удалось скачать», и её можно нажать снова.
Razdor режет новые постройки на куски в фоне, по одной, и сохраняет результат в папку кэша. Пока постройка не разрезана, она стоит одним цельным изображением, как раньше. Потом она встаёт на землю по кускам.

Ограничения этого пути:

Все куски здесь стоят. Куски, лежащие на земле (дворы, мостовые), не выделяются.
Результат делает программа. Проверяйте его по шагам 3 и 6.

Б. Данные, которые поставляет Razdor (сопровождающие)

Мод не может положить свой файл с данными: Razdor читает только data/cards/objects.json и data/lights/objects.json, которые входят в его код. Чтобы постройки мода получили данные, их добавляют в эти файлы и выпускают новую версию. Файлы пишут скрипты в tools/depth/ (подробно в tools/depth/README.md):

cut_sprites.py делает данные о картинках построек (раздел 1 Objects.ugs): карту глубины, куски, опоры и контуры, и помечает каждый кусок как стоящий или лежащий на земле. Карта глубины берётся из Depth Anything V2 Large (CC-BY-NC-4.0, только для офлайн-запуска), и в данные попадают только числа.
Окно терминала
```
CUDA_DEVICE_ORDER=PCI_BUS_ID CUDA_VISIBLE_DEVICES=<номер карты> \
  python3 tools/depth/cut_sprites.py --out data/cards/objects.json "<папка базовой игры>" "<папка мода>"
```
Файл пишется целиком по переданным папкам, поэтому передавайте базу и мод вместе, как в README.
island_cards.py второй шаг: стоящие куски режутся на отдельные связные участки, и у каждого своя опора.
Окно терминала
```
CUT_INSTALLS="<папка базовой игры>:<папка мода>" \
  python3 tools/depth/island_cards.py --data <старый файл> --out <новый файл>
```
detect_points.py находит окна, двери, ворота, трубы и флаги для data/lights/objects.json: Qwen3-VL-4B (Apache-2.0), Florence-2-large (MIT) и тёмные окна по пикселям.
Окно терминала
```
CUDA_DEVICE_ORDER=PCI_BUS_ID CUDA_VISIBLE_DEVICES=<номер карты> \
  python3 tools/depth/detect_points.py --out data/lights/objects.json "<папка мода>"
```

Что нужно: видеокарта NVIDIA с CUDA. cut_sprites.py работает только на RTX 4060 (он проверяет имя карты), detect_points.py на любой карте с CUDA. Нужны Python с torch, transformers, scikit-learn, opencv-python-headless, mapbox-earcut, а также numpy, scipy и Pillow. Модели запускаются офлайн, в репозиторий попадают только числа: ни картинок, ни карт глубины.

Флаги «лежит на земле» ставит cut_sprites.py по глубине. Сопровождающие могут поправить их отдельным классификатором (tools/depth/apply_ground.py, см. docs/flows/ground-classifier.md).

5. Свет

Все настройки света в «Настройках», вкладка «Карта». По умолчанию они выключены, потому что это стиль Razdor, а не оригинал.

«Освещение»: «Выключены», «По часам игры», «Цикл в реальном времени» (тогда появляется строка «Длина суток») или «Постоянный час» (тогда строка «Час»).
«Тени» (с включённым освещением): «Нарисованные» оставляет тени оригинала. «От солнца» убирает их, и каждая постройка отбрасывает свою тень по силуэту картинки. Силуэт проверяйте именно в этом режиме.
«Качество света» (с включённым освещением): «Высокое» даёт свет и тени до восьми построек и факелов фигур, «Среднее» до четырёх, «Низкое» только тёплое свечение. По умолчанию «Высокое» на компьютере и «Среднее» на телефоне.
Окна ночью. С включённым освещением тёмные проёмы на стене светятся тёплым светом. Razdor находит их сам по пикселям картинки: маленький тёмный проём, окружённый непрозрачным ободком, который светлее самого проёма. Светлые пятна цвета крыши в верхней части здания окнами не считаются. Двери, которые выше, чем шире, могут быть крупнее.
«Живая карта» показывает дым из труб и развевающиеся флаги. Их места берутся из данных data/lights, а для изменённой картинки таких данных нет. У постройки мода дыма и флагов не будет, пока сопровождающие не добавят её данные (шаг 4, вариант Б).

Для быстрой проверки ночи включите «Освещение», строку «Постоянный час» и выберите ночной час. Тогда все постройки видны сразу.

6. Проверка

Запустите Razdor с папкой-копией: переменная RAZDOR_DT_DIR указывает на неё (см. Установку модов). Так настоящая игра не меняется.
Откройте карту, где стоят ваши постройки: новую игру или кампанию.
Для каждой постройки проверьте все виды из шага 3: 2.5D, от третьего лица и от первого, с обеих сторон, вблизи и вдали.
Проверьте освещение выключенным и включённым, тени обоими способами, день и ночь.
Сейчас постройки рисуются целыми картинками на всех устройствах. Когда куски включены, на телефоне модель глубины работает на самом телефоне: новые постройки сначала стоят одним изображением, а потом встают на землю по мере нарезки. Уже разрезанные постройки сохраняются в кэше и при следующем запуске не режутся заново.

7. Поделиться модом

Упакуйте мод так, чтобы в нём были только изменённые файлы поверх Community Update, например Graphics/Objects/Objects.ugs. Программы (.exe, .dll), сохранения и логи в каталог не попадают.
Опубликуйте мод на форуме «сокровищница-модов» на Discord-сервере сообщества: каталог собирается из этого форума. Каталог хранит мод как отличия от базы. Если мод сделан поверх другого мода, он требует этот мод.
Мод появится в окне Карты и моды с именем автора и ссылкой на его пост.
Данные о постройках (шаг 4, вариант Б) каталог не добавляет. Попросите сопровождающих Razdor на Discord-сервере сообщества или в GitHub-проекте Razdor. Эти данные начнут работать у всех игроков Razdor, а не только у игроков мода, потому что они привязаны к пикселям картинки.