dvc

2026-08-22 19:10:11 +04:00
parent ebd76275a1
commit 597f4030a7
30 changed files with 877 additions and 1 deletions
@@ -0,0 +1,66 @@
+# Графические MPQ-патчи
+
+В этой директории через DVC версионируется распакованное содержимое всех 15 патчей из
+`graphicsPatches` в `patch-layout.json`. Git хранит небольшие файлы `*.dvc`, а сами ресурсы —
+в S3 remote `customization`. Хэшированные пути в S3 являются внутренней адресацией DVC:
+исходное дерево с обычными именами восстанавливается командой `dvc pull`.
+
+## Первичная настройка
+
+```powershell
+py -m pip install -r requirements-dvc.txt
+Copy-Item .env.example .env # если локального .env ещё нет
+.\configure-dvc.ps1
+py -m dvc pull
+```
+
+Можно скачать один патч, передав его указатель явно:
+
+```powershell
+py -m dvc pull assets/graphics/Data/ruRU/patch-ruRU-X.dvc
+```
+
+Секреты записываются только в `.dvc/config.local`; этот файл исключён из Git. Вместо ключей
+из `.env` можно использовать AWS profile: `.\configure-dvc.ps1 -Profile moonwell`.
+
+## Изменение ресурсов
+
+DVC-кэш использует hardlink на NTFS. Перед ручным изменением дерева отвяжите его от кэша:
+
+```powershell
+py -m dvc unprotect assets/graphics/Data/ruRU/patch-ruRU-X
+# изменить, добавить или удалить файлы
+py -m dvc add assets/graphics/Data/ruRU/patch-ruRU-X
+py -m dvc push
+git add assets/graphics/Data/ruRU/patch-ruRU-X.dvc
+```
+
+Сначала выполняйте `dvc push`, затем коммитьте Git-указатель, чтобы коммит не ссылался на ещё
+не загруженные объекты.
+
+## Импорт MPQ
+
+`mpqextract` принимает встроенный `(listfile)` и любое количество внешних listfile. Он извлекает
+все известные пути, а блоки с неизвестными именами сохраняет в `__mpqmeta__/unresolved/`.
+Манифест `__mpqmeta__/unresolved.json` связывает каждый blob с MPQ-хэшами и индексом блока,
+поэтому содержимое архива не теряется даже при неполном listfile.
+
+```powershell
+cargo run --release --manifest-path tool/Cargo.toml --bin mpqextract -- `
+  'patch.mpq' 'assets/graphics/Data/ruRU/patch-ruRU-N' 'master-list.txt'
+```
+
+В `patch-ruRU-A`, `B`, `S`, `T`, `U` и `W` есть такие безымянные блоки. Для их безопасной
+пересборки нужен авторитетный listfile с исходными путями; пока он не найден, исходные MPQ в
+дистрибуционном S3 остаются каноническими архивами. `mpqpack` намеренно отказывается собирать
+дерево с `__mpqmeta__`, поскольку подмена путей хэшами изменила бы семантику патча.
+
+Полностью разрешённое дерево собирается так:
+
+```powershell
+cargo run --release --manifest-path tool/Cargo.toml --bin mpqpack -- `
+  'assets/graphics/Data/ruRU/patch-ruRU-X' 'build/graphics/patch-ruRU-X.MPQ'
+```
+
+Сводка исходных объектов, DVC-хэшей и количества разрешённых блоков находится в
+`assets/graphics/sources.json`.