moonwell-client/CVPATCH_COMPATIBILITY.md

Совместимость CVPatch и расширенной кастомизации

Документ описывает фактический набор графических MPQ MoonWell для клиента WoW 3.3.5a, build 12340, их порядок загрузки, конфликты DBC, сборку слоя совместимости и серверные требования парикмахерской.

Исходные данные и происхождение

Старые архивы patch-ruRU-A..W относятся к CVPatch (Collection Visual Patch) от Vary/vvladoon. Найденная тема оригинального проекта:

https://forum.uwow.biz/threads/cvpatch-collection-visual-patch-lich-king-3-3-5.296264/

Источник новых архивов утрачен. Единственная сохранённая подпись находится в new customization mpqs/readme.txt:

• patch-a-001.mpq — Model and Textures NPC;
• patch-b-002.mpq — Characters HD The War Within;
• patch-k.mpq — Interface.

Новые архивы нельзя считать официальным или полностью автономным комплектом для 3.3.5a: в них отсутствовал совместимый BarberShopStyle.dbc, а часть DBC содержит данные более новых версий игры.

Установленная часть CVPatch

Патч	Назначение	Зависимости и пересечения
A	Основные модели существ, гуманоидов и транспорта	Основа для старого B
B	Альтернативные модели существ, гуманоидов и транспорта	Требует A
E	Текстуры экипировки в повышенном разрешении	Независимый
H	HD-модели игровых персонажей Leeviathan	Перекрывается новыми X/Y на одинаковых путях
I	Новые модели и текстуры брони и оружия	Изначально требовал H; его item-поля сохраняются при слиянии
M	Карты классических подземелий и пещер	Независимый
S	Эффекты заклинаний и способностей	Содержит собственные spell DBC
T	Текстуры зданий и зон	Независимый
U	Окружение Низины Арати и Ущелья Песни Войны	Независимый
W	Вода	Независимый

Старые буквенные имена не меняются. X, Y и Z специально выбраны после W, чтобы новый комплект и исправления имели приоритет без переименования CVPatch.

Новые исходные архивы

patch-a-001.mpq → patch-ruRU-X.MPQ

Размер исходника — около 2,49 GiB, (listfile) содержит 29 495 файлов:

• 16 023 запечённых NPC-текстуры в Textures\bakednpctextures;
• 13 465 файлов моделей, skin, анимаций и текстур в Character;
• модели стандартных рас и ряда NPC-рас: Vrykul, Naga, Taunka, Forest Troll и других;
• 28 120 BLP, 1 245 ANIM, 94 SKIN и 29 M2;
• 7 DBC.

DBC внутри X:

DBC	Строк	Роль
CharacterFacialHairStyles.dbc	272	Штатный объём лицевой кастомизации
CharHairGeosets.dbc	370	Штатный объём причёсок
CharSections.dbc	10 060	Секции текстур персонажей
CreatureDisplayInfoExtra.dbc	15 477	Дополнительные параметры отображения существ
EmotesTextSound.dbc	782	Звуки текстовых эмоций
HelmetGeosetVisData.dbc	21	Скрытие geoset под шлемами
SpellVisualKitModelAttach.dbc	594	Крепление моделей визуальных эффектов

X нужен текущему комбинированному комплекту для NPC-моделей и запечённых текстур. Для новых причёсок главным является Y, который загружается позже и перекрывает одноимённые таблицы X.

patch-b-002.mpq → patch-ruRU-Y.MPQ

Размер исходника — около 2,80 GiB, (listfile) содержит 36 191 файл:

• 36 180 файлов в Character;
• HD-модели и текстуры десяти стандартных игровых рас WotLK;
• 34 934 BLP, 1 021 ANIM, 125 BONE, 80 SKIN и 20 M2;
• 11 DBC с существенно расширенной кастомизацией.

DBC внутри Y:

DBC	Строк	Роль
CharacterFacialHairStyles.dbc	3 616	Бороды, серьги, рога и другие лицевые варианты
CharHairGeosets.dbc	854	Geoset и номера причёсок
CharHairTextures.dbc	177	Текстуры волос
CharSections.dbc	614 212	Расширенные секции кожи, лица, волос и их сочетаний
CharVariations.dbc	62	Наборы вариаций персонажей
ChrRaces.dbc	41	Описания рас, включая данные за пределами штатного WotLK
CreatureDisplayInfo.dbc	24 282	Display ID моделей
CreatureDisplayInfoExtra.dbc	15 477	Раса, пол, внешность и предметные поля display ID
CreatureFamily.dbc	40	Семейства существ
CreatureModelData.dbc	1 353	Пути и параметры моделей
HelmetGeosetVisData.dbc	65	Расширенные правила отображения под шлемами

Y обязателен для расширенной кастомизации. Z не содержит копии всех этих таблиц и не заменяет Y.

Наличие современных race ID в DBC не добавляет новые игровые расы в ядро или интерфейс 3.3.5a. Текущая интеграция поддерживает расширение внешности десяти штатных рас. Новые игровые расы потребуют отдельной доработки клиента, UI, сетевого протокола и сервера.

patch-k.mpq — не устанавливается

Размер — около 53 MiB, (listfile) содержит 673 файла только в Interface:

• 547 BLP;
• 68 SKIN и 24 M2 для экранов входа и выбора персонажа;
• 15 Lua, 12 XML, TOC и вспомогательные файлы.

Архив меняет Interface\Glues, Interface\GlueXML, модели экранов входа и создания персонажа. Он намеренно исключён из сборки, потому что перекрывает кастомный интерфейс MoonWell. Устанавливать его вручную поверх текущего клиента нельзя без отдельного разбора и слияния UI.

Итоговый порядок загрузки

В локализованной цепочке Data\ruRU используется следующий порядок:

1. штатные архивы клиента, включая patch-ruRU-3.MPQ;
2. старые CVPatch patch-ruRU-A..W;
3. patch-ruRU-X.MPQ — неизменённая копия patch-a-001.mpq;
4. patch-ruRU-Y.MPQ — неизменённая копия patch-b-002.mpq;
5. patch-ruRU-Z.MPQ — сгенерированный слой совместимости MoonWell.

Z является последней инстанцией для конфликтующих DBC. Нельзя переносить его раньше X/Y или устанавливать другой locale MPQ после Z, который содержит те же таблицы.

Содержимое patch-ruRU-Z.MPQ

В текущей сборке Z содержит:

• BarberShopStyle.dbc — расширенная таблица парикмахерской;
• CreatureDisplayInfoExtra.dbc — результат слияния новых display ID и предметных полей CVPatch I;
• SpellVisualKitModelAttach.dbc — более полная версия из CVPatch S;
• CreatureModelData.dbc — сгенерированное слияние штатных, CVPatch и новых моделей;
• CreatureDisplayInfo.dbc — сгенерированное слияние display ID;
• WXLFileData.csv и WXLSpellOverrides.tsv для WarcraftXL.

Последние четыре файла добавляются упаковщиком автоматически; поэтому состав папки src\Data\ruRU\patch-ruRU-Z и готового MPQ не обязан совпадать буквально.

Правила слияния DBC

tool/scripts/build-customization-compat.ps1 выполняет следующие операции:

• берёт штатную базу из patch-ruRU-3.MPQ;
• сохраняет уникальные изменения CreatureModelData из CVPatch A;
• сохраняет уникальные изменения CreatureDisplayInfo из CVPatch B;
• отдаёт приоритет Y при реальном конфликте одной и той же строки;
• переносит изменённые item-поля CreatureDisplayInfoExtra из CVPatch I в новые строки Y;
• восстанавливает SpellVisualKitModelAttach.dbc из CVPatch S;
• генерирует расширенный BarberShopStyle.dbc;
• обновляет входные CreatureModelData.dbc и CreatureDisplayInfo.dbc для генератора MoonWell creatures.

Так Z не позволяет Y случайно уничтожить старые изменения существ, экипировки и эффектов, а генерация MoonWell creatures не уничтожает новые display ID.

Расширенная парикмахерская

Причина исходного падения

Y расширил:

• CharHairGeosets.dbc с 370 до 854 строк;
• CharacterFacialHairStyles.dbc с 272 до 3 616 строк.

При этом исходные новые MPQ не содержали BarberShopStyle.dbc. Клиент продолжал использовать штатную таблицу на 491 строку. При выборе нового варианта функция GetBarberShopTotalCost не находила запись, после чего WoW падал с ERROR #132 / ACCESS_VIOLATION. В зафиксированном крэше вызов шёл от BarberShopFrameSelector1Next.

Как сформирована новая таблица

Генератор:

• сохраняет все 491 штатную строку и исходную строковую таблицу байт-в-байт;
• добавляет отсутствующие причёски из CharHairGeosets.dbc Y;
• добавляет отсутствующую растительность и украшения из CharacterFacialHairStyles.dbc Y;
• работает только с сочетаниями расы, пола и типа, уже существующими в штатном BarberShopStyle.dbc, то есть с поддерживаемыми расами WotLK;
• сохраняет штатные строки типа 3 для особой кастомизации рыцарей смерти;
• назначает новые уникальные ID после максимального штатного ID;
• проверяет отсутствие дубликатов и полноту покрытия.

Результат:

• 3 765 строк всего;
• 152 новые причёски;
• 3 122 новых варианта растительности, серёг и других особенностей;
• максимальный номер лицевого варианта — 255, что помещается в поле внешности персонажа 3.3.5a.

В исходном комплекте нет названий новых стилей. Поэтому сейчас они отображаются как New hairstyle N и New appearance N. Это только подписи: на выбор модели и сохранение внешности они не влияют.

Что требуется клиенту и серверу

Компонент	Клиент	Сервер
patch-ruRU-X.MPQ	Да, для текущего комплекта NPC/персонажей	Нет
patch-ruRU-Y.MPQ	Да, для моделей, текстур и основных customization DBC	Нет
patch-ruRU-Z.MPQ	Да, для совместимости и исправления парикмахерской	Нет как MPQ
Сгенерированный BarberShopStyle.dbc	Уже находится внутри Z	Да, отдельным DBC
Остальные клиентские DBC из X/Y	Загружаются из MPQ	Для текущих десяти рас не копируются

Серверную копию нужно положить в каталог DBC worldserver, обычно:

<server>/data/dbc/BarberShopStyle.dbc

После замены требуется полный перезапуск worldserver: DBC загружаются при старте. Клиентская и серверная копии BarberShopStyle.dbc должны быть одним и тем же сгенерированным файлом. Без серверной копии клиент больше не должен падать при переключении, но сервер может отклонить применение нового стиля или неверно рассчитать его стоимость.

Готовая серверная копия после запуска генератора находится в:

build/customization-compat/server-dbc/BarberShopStyle.dbc

Тот же отслеживаемый исходник для Z находится в:

src/Data/ruRU/patch-ruRU-Z/DBFilesClient/BarberShopStyle.dbc

Не следует копировать на сервер ChrRaces.dbc, CharSections.dbc или весь набор DBC из Y без отдельной задачи и проверки ядра.

Сборка

Предварительные условия

В .env должен быть задан корректный WOW_HOME. В клиенте должны находиться:

• штатный Data\ruRU\patch-ruRU-3.MPQ;
• CVPatch A, B, I и S, используемые генератором как источники слияния;
• остальные CVPatch, если они должны остаться в итоговой установке.

В репозитории должны оставаться:

• new customization mpqs\patch-a-001.mpq;
• new customization mpqs\patch-b-002.mpq;
• tool\target\release\mpqread.exe.

Пересоздание DBC совместимости

.\tool\scripts\build-customization-compat.ps1

Скрипт обновляет:

assets/dbc/3.3.5a/CreatureModelData.dbc
assets/dbc/3.3.5a/CreatureDisplayInfo.dbc
src/Data/ruRU/patch-ruRU-Z/DBFilesClient/CreatureDisplayInfoExtra.dbc
src/Data/ruRU/patch-ruRU-Z/DBFilesClient/SpellVisualKitModelAttach.dbc
src/Data/ruRU/patch-ruRU-Z/DBFilesClient/BarberShopStyle.dbc
build/customization-compat/server-dbc/BarberShopStyle.dbc

Упаковка MPQ

.\tool\target\release\tool.exe .\src .\dist

Упаковщик:

• собирает Z из исходников и сгенерированных MoonWell DBC;
• не копирует внешние графические X/Y в dist и не включает их в managed manifest;
• не добавляет patch-k.mpq.

Для полной локальной сборки и синхронизации клиента можно использовать:

.\run.ps1 -Env local

Этот сценарий также собирает WarcraftXL, останавливает блокирующие процессы и синхронизирует весь dist в WOW_HOME. Для проверки только изменения Z можно собрать архив упаковщиком и скопировать лишь dist\Data\ruRU\patch-ruRU-Z.MPQ.

Сборка этих архивов не должна автоматически изменять manifest.json. Манифест обновляется владельцем проекта отдельно после локальной проверки.

Исходники MPQ и установленные копии

Файлы в new customization mpqs используются только как локальные источники генератора таблиц совместимости. В готовом клиенте X и Y управляются отдельно от репозиторных патчей.

Списки репозиторных и внешних графических патчей находятся в patch-layout.json. deploy.ps1, run.ps1, генератор манифеста и S3 uploader синхронизируют только список repositoryPatches. Пути из graphicsPatches сохраняются без копирования и удаления. Если один путь указан в обоих списках, repositoryPatches имеет приоритет.

Z не консолидирует многогигабайтные модели и текстуры X/Y. Удаление X или Y из клиента не освобождается наличием текущих DBC в Z.

Проверка после сборки

Минимальный сценарий локальной проверки:

1. Полностью закрыть WoW перед заменой MPQ.
2. Проверить наличие X, Y и Z в Data\ruRU.
3. Запустить клиент и открыть создание персонажа.
4. Проверить оба пола и основные расы, пролистать причёски и лицевые варианты.
5. Создать тестового персонажа, войти в мир и проверить модель после повторного входа.
6. Открыть парикмахерскую и несколько раз нажать вперёд/назад у каждого селектора.
7. Проверить отображение стоимости и отсутствие ERROR #132.
8. Применить новый стиль, выйти из мира и войти снова.
9. Проверить старую броню, NPC-модели и эффекты заклинаний, которые могли быть затронуты конфликтующими DBC.

Для шага 8 сервер уже должен использовать сгенерированный BarberShopStyle.dbc.

Диагностика

Симптом	Вероятная причина
Новых причёсок нет	Отсутствует Y или более поздний MPQ перекрыл его CharHairGeosets/CharSections
Модель отсутствует или отображается неверно	X/Y не скопированы полностью либо повреждены многогигабайтные архивы
Падение при переключении в парикмахерской	Z отсутствует, загружен раньше Y или его BarberShopStyle.dbc перекрыт
Вариант выбирается, но не применяется	На сервере остался штатный BarberShopStyle.dbc или worldserver не перезапущен
Исчезли старые NPC/display ID	Z не пересобран после изменения источников CVPatch или Y
Проблемы со старой экипировкой	Потеряны item-поля CVPatch I в CreatureDisplayInfoExtra.dbc
Изменился экран входа/создания персонажа	patch-k.mpq был установлен вручную

Перед заменой рабочего Z рекомендуется сохранять предыдущий архив. Последняя локальная резервная копия, созданная во время исправления парикмахерской:

build/customization-compat/client-backup/patch-ruRU-Z.before-barbershop.MPQ