SRHD XenoModKit 0.10.2

Headless modding toolkit for Space Rangers HD: A War Apart / Космические рейнджеры HD: Революция.

Публичная GitHub-версия универсального SRHD ModKit для анализа, изменения и безопасной сборки модов. Автор: Xenomorphchyma.

Публичное название — SRHD XenoModKit. Внутренние имена SRHD ModKit, srhd_modkit, srhd.py и srhd.cmd сохранены для совместимости.

Что умеет

• проверять мод целиком и выпускать воспроизводимый ZIP с SHA-256-манифестом;
• читать и изменять BlockPar DAT без ручного открытия редактора;
• анализировать, декомпилировать, сравнивать, изменять и собирать RSON, модульные RSM, legacy-SVR и SCR;
• обнаруживать опасные runtime-шаблоны, связанные с зависанием на «Проходит время»;
• проверять регистрацию скриптов в Main.dat и согласованность CacheData;
• находить ошибки CP1251, UTF-8 и повреждённый русский текст до запуска игры;
• нативно проверять и преобразовывать GI ↔ PNG без RangerTools или Pillow;
• читать, проверять и извлекать GAI, HAI и PKG;
• детерминированно собирать подтверждённые разновидности GAI и PKG;
• нативно читать, проверять, редактировать через JSON и собирать текстовые квесты QM/QMM без TGE;
• анализировать зависимости и конфликты активного набора модов;
• собирать варианты проекта, кэшировать дорогие компиляции и публиковать папку/ZIP из одного srhd-modkit.toml;
• создавать и статически проверять Host API V1 x86-плагины XenoNativeLoader 0.6.5+ (проверено с 0.6.7 из XenoMods), не исполняя недоверенную DLL;
• сохранять неизвестные форматы побайтно и отмечать неполное покрытие.

ModKit разворачивает мод в игру только по явной release deploy, project deploy либо настроенной project publish, не изменяет ModCFG.txt и не требует GUI.

Что изменилось в 0.10.2

• Исправлены ложные ошибки для графовых TVar Array: повторный newarray не обязателен, а доказанный ArrayDelete(array, 0) допускает последующий обход с нуля до сброса массива.
• Прямой ограниченный обход GalaxyStar(i) при 0 <= i < GalaxyStars() распознаётся без лишнего null-guard; сохранённые индексы, изменение счётчика и условные присваивания не получают общего исключения.
• script build и Python API принимают точечный --allow CODE[:GLOB]. Project workflow передаёт свои исключения в RSON-компиляцию; подавленные сообщения остаются в JSON, а набор исключений входит в ключ кэша.
• Исправлен кэш исходников внутри папки мода: случайный путь staging больше не вызывает постоянную пересборку; project plan и build согласованы.
• Добавлены перекрёстные тесты CacheData для BlockParEditor 1.9/2.1 и трёх кодировок, а также реальная MSVC x86-сборка Native Loader-плагина с проверкой отсутствующей DLL, кэша и повторяемости ZIP.
• Обновлены руководство по скриптам, документация проектной сборки и скилл для нейросетей.

Проверка выпуска: 400 тестов и 42 подтеста прошли, 2 теста пропущены. Четыре интеграционных теста останавливаются при legacy SVR → RSON с Runtime error 217 внешнего RScript 4.10f. Сбой воспроизведён и до этих изменений; он не считается исправленным. RScript 4.15f отдельно успешно пересобрал оба проверяемых планетарных мода. Не отключайте проверку результата ради обхода ошибки старого EXE.

Быстрый старт

Требуется Windows 10/11 x64 и Python 3.12 или новее. Для проверки поведения мода в игре нужна установленная Space Rangers HD, но путь к игре не требуется для запуска самой библиотеки.

git clone https://github.com/Xenomorphchyma/SRHD-XenoModKit.git
Set-Location SRHD-XenoModKit
python -B srhd.py --version
python -B srhd.py --help

Обязательных Python-пакетов нет. Установка через pip для запуска srhd.py не нужна.

Проверить доступность дополнительных кодеков:

python -B srhd.py tools

Установить DAT- и script-кодеки

Для полной работы с DAT, RSON/RSM/SCR и legacy-SVR запустите:

.\scripts\setup-tools.ps1

Скрипт скачивает BlockParEditor 2.1, RScript 4.15f и rsmc из официальных зафиксированных релизов, проверяет SHA-256 архивов и EXE и кладёт их рядом с клоном:

Рабочая папка/
├── SRHD-XenoModKit/
├── BlockParEditor/
├── RScript/
├── RScript410/
└── RSMCompiler/

При обновлении уже проверенные 1.9/4.10f не удаляются: установщик переносит их в BlockParEditor19/ и RScript410/. На чистой установке 4.10f также добавляется в RScript410/, потому что она нужна для legacy RSON ↔ SVR, которой больше нет в CLI 4.15f.

Другой каталог можно задать явно:

.\scripts\setup-tools.ps1 -ToolsRoot C:\SRHD-Tools
python -B srhd.py tools --tools-root C:\SRHD-Tools

Подробные источники, контрольные суммы и ручная установка описаны в THIRD_PARTY_TOOLS_RU.md.

Что работает без дополнительных загрузок

Возможность	После клонирования	Дополнительный инструмент
структура мода, ModuleInfo, пути, мусорные файлы	да	—
кодировки и русский игровой текст	да	—
SCR binary-аудит и runtime-lint RSON	да	—
GI ↔ PNG, включая режимы 0_32, 0_16, 2	да	—
GAI/HAI/PKG чтение и проверка	да	—
GAI/PKG сборка с обратной проверкой	да	—
QM/QMM чтение, JSON-редактирование, сборка и аудит	да	—
неизвестные форматы и SHA-256-манифест	да	—
DAT ↔ TXT и полный DAT-аудит	после setup	BlockParEditor 2.1
RSON ↔ SCR, настоящий CLI SCR → RSON	после setup	RScript 4.15f
RSM export/build/validate	после setup	RScript 4.15f + rsmc
RSON ↔ SVR (legacy)	после setup	совместимый RScript 4.10f

Первые команды

Быстрый аудит во время разработки:

python -B srhd.py audit C:\Mods\MyMod --profile dev --json

Полная проверка и релиз:

python -B srhd.py release check C:\Mods\MyMod --json
python -B srhd.py release build C:\Mods\MyMod C:\Releases\MyMod.zip --json
python -B srhd.py release plan C:\Work\MyMod "C:\Games\Space Rangers HD\Mods" --prefix OtherMods/MyMod --json
python -B srhd.py release deploy C:\Work\MyMod "C:\Games\Space Rangers HD\Mods" --prefix OtherMods/MyMod --overwrite --json

release deploy принимает корень Mods/Builds, а --prefix — путь мода внутри него. Существующая целевая папка заменяется только при явном --overwrite; это точная замена, поэтому файлы, удалённые из проекта, не сохраняются от прежней сборки. Исходники исключены по умолчанию. Release staging is audited again after all excludes are applied. A source Source/.../Main.txt does not replace runtime CFG/Main.dat, and symlinks or junctions are rejected instead of silently omitted. Unknown formats remain non-blocking by default; CI can opt into --require-complete. Failed audit execution is exposed as operational_failure=true and exit code 3.

Для постоянной разработки удобнее один раз добавить проектный файл, а затем использовать короткие команды:

python -B srhd.py project init C:\Work\MyMod --json
python -B srhd.py project plan --variant earth-test --json
python -B srhd.py project doctor --json
python -B srhd.py project validate
python -B srhd.py project build --variant earth-test --json
python -B srhd.py project deploy --variant earth-test --target game --dry-run --json
python -B srhd.py project publish --variant release --json

Проверка обновления и языков:

python -B srhd.py release upgrade-check C:\Work\MyMod-old C:\Work\MyMod-new --json
python -B srhd.py lang coverage C:\Work\MyMod-new --base Rus --json
python -B srhd.py schema validate C:\Work\MyMod-new.audit.json --json
python -B srhd.py native init C:\Work\MyNativeMod --id MyNativeRuntime --json
python -B srhd.py native validate C:\Work\MyNativeMod --json

Полная схема, варианты, кэш, цели и восстановление описаны в руководстве по проектной сборке.

Безопасная рабочая копия:

python -B srhd.py stage C:\Mods\Original C:\Work\MyMod

DAT / BlockPar:

python -B srhd.py dat tree C:\Work\MyMod\CFG\Main.dat --json
python -B srhd.py dat decode C:\Work\MyMod\CFG\Main.dat C:\Work\Main.txt
python -B srhd.py dat validate C:\Work\MyMod\CFG\Main.dat --json

Скрипты:

python -B srhd.py script audit-mod C:\Work\MyMod --json
python -B srhd.py script lint-runtime C:\Work\MyMod --strict --json
python -B srhd.py script decompile C:\Work\Mod_Name.scr C:\Work\Mod_Name.rson `
  --lang-dat C:\Work\Lang.dat --json
python -B srhd.py script compare-scr C:\Work\Original.scr C:\Work\Patched.scr --json
python -B srhd.py script compare-storage C:\Work\Old.rson C:\Work\New.rson --json
python -B srhd.py script set-code C:\Work\Script.rson C:\Work\Script.edited.rson `
  --id 17 --field OnActCode --code-file C:\Work\player-buy-handler.txt
python -B srhd.py script build C:\Work\Script.rson --scr C:\Work\Script.scr --lang C:\Work\Lang.txt
python -B srhd.py script export-rsm C:\Work\Script.rson C:\Work\ScriptRsm --split
python -B srhd.py script validate-rsm C:\Work\ScriptRsm\main.rsm --lang-base C:\Work\Lang.dat --json
python -B srhd.py script build-rsm C:\Work\ScriptRsm\main.rsm --scr C:\Work\Script.scr `
  --lang-dat C:\Work\Lang.dat --lang-base C:\Work\Lang.base.dat --json

Текстовые квесты без TGE:

python -B srhd.py quest info C:\Work\Quest.qmm --json
python -B srhd.py quest validate C:\Work\Quest.qmm --json
python -B srhd.py quest export-json C:\Work\Quest.qmm C:\Work\Quest.json
python -B srhd.py quest build C:\Work\Quest.json C:\Work\Quest.edited.qmm --json
python -B srhd.py quest roundtrip C:\Work\Quest.edited.qmm --json

GI/PNG без дополнительных программ:

python -B srhd.py convert gi-png C:\Work\Images -o C:\Work\PNG
python -B srhd.py convert png-gi C:\Work\PNG -o C:\Work\Images --mode 0_32

0_32 сохраняет RGBA пиксель-в-пиксель; 0_16 использует RGB565, а режим 2 — три RLE-слоя с RGB565 и отдельной прозрачностью. Старые GI типов 1, 3, 4 и служебные GI с нулевым холстом сохраняются без изменений и честно получают unsupported, поскольку их нельзя безопасно представить как PNG. При выводе в DATA\ItemsUseless режим 2 рекомендуется для совместимости крупного слота и уменьшенных карточек предмета. Если явно выбран другой режим, конвертация всё равно завершается, а CLI/Python API возвращает рекомендацию gi-items-useless-mode-2-recommended.

Для поддерживаемого GI команды resource info --json и resource verify --json включают alpha_geometry: непустые границы с исключительным finish_x/finish_y, прозрачные поля, их асимметрию и взвешенный по альфе центр. Это диагностические числа, а не автоматическая оценка художественной композиции.

По умолчанию небольшой проект RScript получает 60 секунд без подтверждённого прогресса и не менее 600 секунд общего времени. Для крупных проектов оба окна автоматически растут по размеру RSON/SCR, числу объектов и строк кода. Изменение ожидаемого файла, файловый ввод-вывод процесса или переход шага скрытой автоматизации сдвигают окно; простая загрузка CPU прогрессом не считается. Положительный --timeout задаёт явный общий предел, а 0 у script build или обоих таймаутов декомпиляции и сравнения отключает оба ограничения.

Совместимость активных модов без изменения ModCFG.txt:

python -B srhd.py compat "C:\Games\Space Rangers HD\Mods\ModCFG.txt" `
  --mods-root "C:\Games\Space Rangers HD\Mods" --json

load_order и владельцы пересекающихся путей выводятся в эффективном порядке движка: стабильная сортировка по возрастанию Priority, где отсутствующее поле равно нулю, а CurrentMod разрешает равенство. Исходная позиция остаётся в configured_order; compat никогда не переписывает конфигурацию. Даже при известном порядке сложное наложение сохраняет resolution: unknown, пока семантика конкретного BlockPar/SCR/CacheData-пересечения не доказана.

Безопасность и границы

• release build создаёт staging-копию, проверяет архив повторным чтением и сверяет хэши.
• Ошибки блокируют релиз; предупреждения блокируются только с --warnings-as-errors.
• unsupported означает неполное покрытие, а не повреждение файла.
• GUI заблокирован по умолчанию и не нужен для штатных сценариев.
• script validate до запуска RScript ловит незакрытые строки/комментарии/скобки и случайный русский текст вне строки или комментария — известную причину зависания старого компилятора.
• script decompile в RScript 4.15f использует настоящий CLI; 4.10f запускается только как legacy-бэкенд на изолированном невидимом desktop. Исходный SCR не изменяется, а RSON публикуется лишь после цикла SCR → RSON → SCR.
• Сбой импорта непустого Lang.dat не скрывается: JSON содержит структурированную диагностику, а восстановление без диалогов выполняется только по явному --fallback-without-lang.
• Машинные отчёты декомпиляции, сравнения и совместимости persistent-хранилища имеют схемы srhd-modkit-decompile-v1, srhd-modkit-scr-compare-v1 и srhd-modkit-storage-compat-v1.
• Непроверенное восстановление удаляется; сохранить его можно только по отдельному явному пути --keep-unverified. --deep-roundtrip дополнительно проверяет стабильность числа объектов, связей, строк кода и типов после второго восстановления.
• QM/QMM writer не меняет исходник: JSON собирается в новый QMM, затем файл перечитывается и сравнивается с моделью. Проверка формата не заменяет прохождение квеста в игре.
• HAI поддерживается только для чтения и проверки.
• Статический анализ не заменяет запуск в игре, проверку сохранений и конкретной комбинации модов.

Документация

• Подробное руководство на русском
• Архитектура аудита и границы форматов
• Скриптинг SRHD и runtime-lint
• Текстовые квесты QM/QMM
• Проектная сборка, варианты, кэш и deploy
• Внешние инструменты и SHA-256
• Уведомления о сторонних исследованиях форматов
• Авторство

Codex skill

В репозитории находится headless-скилл .agents/skills/srhd-modkit. При работе Codex внутри клона он обнаруживается автоматически; явный вызов:

$srhd-modkit

Скилл требует использовать CLI/Python API, не запускать GUI, не изменять установленную игру и честно сообщать о неполном покрытии.

Тесты

python -B -m unittest discover -s tests -v

Текущий набор из 325 тестов проверяет нативные PNG/GI, лексический preflight, прогресс-зависимые таймауты, fail-closed декомпиляцию, глубокий round-trip, RScript 4.10f/4.15f, RSM/rsmc, BlockPar 2.1 и завершение скрытого дерева процессов при обрыве агента, а также QM/QMM reader/writer, формулы квестов и JSON-цикл. На локальном корпусе глубоко проверено 3098 из 3131 GI; оставшиеся 33 корректно классифицированы как unsupported. Дополнительно dev-аудит был выполнен на 425 установленных модах без падений валидаторов. В корпусе распознано 48 QM/QMM.

Авторство

SRHD XenoModKit создан и поддерживается Xenomorphchyma. Сторонние кодеки и форматы принадлежат их соответствующим авторам; они перечислены отдельно и не присваиваются проекту.