fparkan/tools

Инструменты в каталоге tools

archive_roundtrip_validator.py

Скрипт предназначен для валидации документации по форматам NRes и RsLi на реальных данных игры.

Что делает утилита:

• находит архивы по сигнатуре заголовка (а не по расширению файла);
• распаковывает архивы в структуру manifest.json + entries/*;
• собирает архивы обратно из manifest.json;
• выполняет проверку unpack -> repack -> byte-compare;
• формирует отчёт о расхождениях со спецификацией.

Скрипт не изменяет оригинальные файлы игры. Рабочие файлы создаются только в указанном --workdir (или во временной папке).

Поддерживаемые сигнатуры

• NRes (4E 52 65 73)
• RsLi в файловом формате библиотеки: NL 00 01

Основные команды

Сканирование архива по сигнатурам:

python3 tools/archive_roundtrip_validator.py scan --input tmp/gamedata

Распаковка/упаковка одного NRes:

python3 tools/archive_roundtrip_validator.py nres-unpack \
  --archive tmp/gamedata/sounds.lib \
  --output tmp/work/nres_sounds

python3 tools/archive_roundtrip_validator.py nres-pack \
  --manifest tmp/work/nres_sounds/manifest.json \
  --output tmp/work/sounds.repacked.lib

Распаковка/упаковка одного RsLi:

python3 tools/archive_roundtrip_validator.py rsli-unpack \
  --archive tmp/gamedata/sprites.lib \
  --output tmp/work/rsli_sprites

python3 tools/archive_roundtrip_validator.py rsli-pack \
  --manifest tmp/work/rsli_sprites/manifest.json \
  --output tmp/work/sprites.repacked.lib

Полная валидация документации на всём наборе данных:

python3 tools/archive_roundtrip_validator.py validate \
  --input tmp/gamedata \
  --workdir tmp/validation_work \
  --report tmp/validation_report.json \
  --fail-on-diff

Формат распаковки

Для каждого архива создаются:

• manifest.json — все поля заголовка, записи, индексы, смещения, контрольные суммы;
• entries/*.bin — payload-файлы.

Имена файлов в entries включают индекс записи, поэтому коллизии одинаковых имён внутри архива обрабатываются корректно.

init_testdata.py

Скрипт инициализирует тестовые данные по сигнатурам архивов из спецификации:

• NRes (4E 52 65 73);
• RsLi (NL 00 01).

Что делает утилита:

• рекурсивно сканирует все файлы в --input;
• копирует найденные NRes в --output/nres/;
• копирует найденные RsLi в --output/rsli/;
• сохраняет относительный путь исходного файла внутри целевого каталога;
• создаёт целевые каталоги автоматически, если их нет.

Базовый запуск:

python3 tools/init_testdata.py --input tmp/gamedata --output testdata

Если целевой файл уже существует, скрипт спрашивает подтверждение перезаписи (yes/no/all/quit).

Для перезаписи без вопросов используйте --force:

python3 tools/init_testdata.py --input tmp/gamedata --output testdata --force

Проверки надёжности:

• --input должен существовать и быть каталогом;
• если --output указывает на существующий файл, скрипт завершится с ошибкой;
• если --output расположен внутри --input, каталог вывода исключается из сканирования;
• если stdin неинтерактивный и требуется перезапись, нужно явно указать --force.

msh_doc_validator.py

Скрипт валидирует ключевые инварианты из документации /Users/valentineus/Developer/personal/fparkan/docs/specs/msh.md на реальных данных.

Проверяемые группы:

• модели *.msh (вложенные NRes в архивах NRes);
• текстуры Texm (type_id = 0x6D786554);
• эффекты FXID (type_id = 0x44495846).

Что проверяет для моделей:

• обязательные ресурсы (Res1/2/3/6/13) и известные опциональные (Res4/5/7/8/10/15/16/18/19);
• size/attr1/attr3 и шаги структур по таблицам;
• диапазоны индексов, батчей и ссылок между таблицами;
• разбор Res10 как len + bytes + NUL для каждого узла;
• матрицу слотов в Res1 (LOD/group) и границы по Res2/Res7/Res13/Res19.

Быстрый запуск:

python3 tools/msh_doc_validator.py scan --input testdata/nres
python3 tools/msh_doc_validator.py validate --input testdata/nres --print-limit 20

С отчётом в JSON:

python3 tools/msh_doc_validator.py validate \
  --input testdata/nres \
  --report tmp/msh_validation_report.json \
  --fail-on-warnings

msh_preview_renderer.py

Примитивный программный рендерер моделей *.msh без внешних зависимостей.

• вход: архив NRes (например animals.rlb) или прямой payload модели;
• выход: изображение PPM (P6);
• использует Res3 (позиции), Res6 (индексы), Res13 (батчи), Res1/Res2 (выбор слотов по lod/group).

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

python3 tools/msh_preview_renderer.py list-models --archive testdata/nres/animals.rlb

Сгенерировать тестовый рендер:

python3 tools/msh_preview_renderer.py render \
  --archive testdata/nres/animals.rlb \
  --model A_L_01.msh \
  --output tmp/renders/A_L_01.ppm \
  --width 800 \
  --height 600 \
  --lod 0 \
  --group 0 \
  --wireframe

Ограничения:

• инструмент предназначен для smoke-теста геометрии, а не для пиксельно-точного рендера движка;
• текстуры/материалы/эффектные проходы не эмулируются.

msh_export_obj.py

Экспортирует геометрию *.msh в Wavefront OBJ, чтобы открыть модель в Blender/MeshLab.

• вход: NRes архив (например animals.rlb) или прямой payload модели;
• выбор геометрии: через Res1 slot matrix (lod/group) как в рендерере;
• опция --all-batches экспортирует все батчи, игнорируя slot matrix.

Показать модели в архиве:

python3 tools/msh_export_obj.py list-models --archive testdata/nres/animals.rlb

Экспорт в OBJ:

python3 tools/msh_export_obj.py export \
  --archive testdata/nres/animals.rlb \
  --model A_L_01.msh \
  --output tmp/renders/A_L_01.obj \
  --lod 0 \
  --group 0

Файл OBJ можно открыть напрямую в Blender (File -> Import -> Wavefront (.obj)).