From ef9323772446e25a8d3dc5ee0e3954f921bb0074 Mon Sep 17 00:00:00 2001 From: Valentin Popov Date: Tue, 10 Feb 2026 01:58:16 +0400 Subject: Add .gitignore for Python and project-specific files; implement archive roundtrip validator - Updated .gitignore to include common Python artifacts and project-specific files. - Added `archive_roundtrip_validator.py` script for validating NRes and RsLi formats against real game data. - Created README.md for the tools directory, detailing usage and supported signatures. - Enhanced nres.md with practical nuances and empirical checks for game data. --- tools/README.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 tools/README.md (limited to 'tools/README.md') diff --git a/tools/README.md b/tools/README.md new file mode 100644 index 0000000..6059090 --- /dev/null +++ b/tools/README.md @@ -0,0 +1,71 @@ +# Инструменты в каталоге `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` + +## Основные команды + +Сканирование архива по сигнатурам: + +```bash +python3 tools/archive_roundtrip_validator.py scan --input tmp/gamedata +``` + +Распаковка/упаковка одного NRes: + +```bash +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: + +```bash +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 +``` + +Полная валидация документации на всём наборе данных: + +```bash +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` включают индекс записи, поэтому коллизии одинаковых имён внутри архива обрабатываются корректно. -- cgit v1.2.3