fparkan/docs/specs/wear.md

Wear table (WEAR)

WEAR — текстовый ресурс, который связывает слоты wear с именами материалов и lightmap.

Связанные страницы:

• Material (MAT0)
• Texture (Texm)

1. Контейнер

• Тип ресурса: 0x52414557 (WEAR).
• Обычно хранится как *.wea внутри world/mission архивов.

2. Формат текста

<wearCount:int>
<legacyId:int> <materialName>
... (wearCount строк)

[пустая строка]
[LIGHTMAPS
<lightmapCount:int>
<legacyId:int> <lightmapName>
... (lightmapCount строк)]

legacyId читается, но логика выбора работает по имени.

3. Совместимость парсинга

В движке используются два режима чтения (из файла и из буфера), у которых различается обработка блока LIGHTMAPS.

Практическое правило для полного совпадения:

• если присутствует блок LIGHTMAPS, перед строкой LIGHTMAPS должна быть пустая строка-разделитель.

4. Runtime-ограничения

• Число wear-таблиц в менеджере ограничено: максимум 70.
• Для wearCount <= 0 ресурс считается некорректным.
• Для LIGHTMAPS блока lightmapCount <= 0 — также ошибка формата.

5. Поведение резолва

5.1. Материал

Для каждого wear-слота:

1. Ищется материал по имени.
2. Если не найден — используется fallback (DEFAULT, затем индекс 0).

5.2. Lightmap

Для каждого lightmap-слота:

1. Ищется текстура lightmap по имени.
2. Если не найдено — слот получает -1.

6. Handle-кодирование

Движок кодирует ссылку на material-slot как:

handle = (tableIndex << 16) | wearIndex

• tableIndex — номер wear-таблицы.
• wearIndex — индекс строки внутри таблицы.

7. Правила writer/editor

1. Сохранять порядок строк.
2. Не переставлять и не нормализовать legacyId.
3. Для совместимости buffer-парсинга сохранять пустую строку перед LIGHTMAPS.
4. Проверять, что число строк соответствует wearCount/lightmapCount.

8. Статус валидации

• Поведение WEAR согласовано с текущей спецификацией материалов/текстур и runtime-пайплайном.
• Корпусные проверки связки WEAR -> MAT0 -> Texm включены в текущий валидаторный контур проекта.

9. Статус покрытия и что осталось до 100%

Закрыто:

1. Текстовый формат WEAR, включая блок LIGHTMAPS.
2. Handle-кодирование material slot и fallback-резолв.
3. Правила совместимого writer/editor path.

Осталось:

1. Полная спецификация edge-case форматов строк (кодировки, редкие разделители, возможные legacy-варианты).
2. Формализация всех ограничений менеджера wear-таблиц в runtime (лимиты и политики вытеснения).
3. Интеграционные parity-тесты на полном цикле «модель -> wear -> material -> texture/lightmap».