300 lines
16 KiB
Markdown
300 lines
16 KiB
Markdown
# Materials + Texm
|
||
|
||
Документ описывает материалы, текстуры, палитры, блоки `WEAR` / `LIGHTMAPS` и формат `Texm`.
|
||
|
||
---
|
||
|
||
## 2.1. Архитектура материальной системы
|
||
|
||
Материальная подсистема реализована в `World3D.dll` и включает:
|
||
|
||
- **Менеджер материалов** (`LoadMatManager`) — объект размером 0x470 байт (1136), хранящий до 140 таблиц материалов (поле `+572`, `this[143]`).
|
||
- **Библиотека палитр** (`SetPalettesLib`) — NRes‑архив с палитрами.
|
||
- **Библиотека текстур** (`SetTexturesLib`) — путь к файлу/каталогу текстур.
|
||
- **Библиотека материалов** (`SetMaterialLib`) — NRes‑архив с данными материалов.
|
||
- **Библиотека lightmap'ов** (`SetLightMapLib`) — опциональная.
|
||
|
||
### Загрузка палитр (sub_10002B40)
|
||
|
||
Палитры загружаются из NRes‑архива по именам. Система перебирает буквы `'A'`..'Z'` (26 категорий) × 11 суффиксов, формируя имена вида `"A<suffix>.pal"`. Каждая палитра загружается через `niOpenResFile` → `niReadData` и регистрируется как текстурный объект в графическом движке.
|
||
|
||
Максимальное количество палитр: 26 × 11 = **286**.
|
||
|
||
## 2.2. Запись материала (76 байт)
|
||
|
||
Материал представлен записью размером **76 байт** (19 DWORD). Поля восстановлены из функции интерполяции `sub_10003030` и функций `sub_100031F0` / `sub_10003680`.
|
||
|
||
| Смещение | Размер | Тип | Интерполяция | Описание |
|
||
|----------|--------|--------|--------------|--------------------------------------|
|
||
| 0 | 4 | uint32 | Нет | `flags` — тип/режим материала |
|
||
| 4 | 4 | float | Бит 1 (0x02) | Цветовой компонент A — R |
|
||
| 8 | 4 | float | Бит 1 (0x02) | Цветовой компонент A — G |
|
||
| 12 | 4 | float | Бит 1 (0x02) | Цветовой компонент A — B |
|
||
| 16 | 4 | — | Нет | Зарезервировано / паддинг |
|
||
| 20 | 4 | float | Бит 0 (0x01) | Цветовой компонент B — R |
|
||
| 24 | 4 | float | Бит 0 (0x01) | Цветовой компонент B — G |
|
||
| 28 | 4 | float | Бит 0 (0x01) | Цветовой компонент B — B |
|
||
| 32 | 4 | float | Бит 4 (0x10) | Скалярный параметр (power / opacity) |
|
||
| 36 | 4 | float | Бит 2 (0x04) | Цветовой компонент C — R |
|
||
| 40 | 4 | float | Бит 2 (0x04) | Цветовой компонент C — G |
|
||
| 44 | 4 | float | Бит 2 (0x04) | Цветовой компонент C — B |
|
||
| 48 | 4 | — | Нет | Зарезервировано / паддинг |
|
||
| 52 | 4 | float | Бит 3 (0x08) | Цветовой компонент D — R |
|
||
| 56 | 4 | float | Бит 3 (0x08) | Цветовой компонент D — G |
|
||
| 60 | 4 | float | Бит 3 (0x08) | Цветовой компонент D — B |
|
||
| 64 | 4 | — | Нет | Зарезервировано / паддинг |
|
||
| 68 | 4 | int32 | Нет | `textureIndex` — индекс текстуры |
|
||
| 72 | 4 | int32 | Нет | Дополнительный параметр |
|
||
|
||
### Маппинг компонентов на D3D Material (предположительный)
|
||
|
||
По аналогии со стандартной структурой `D3DMATERIAL7`:
|
||
|
||
| Компонент | Вероятное назначение | Биты интерполяции |
|
||
|--------------|----------------------|-------------------|
|
||
| A (+4..+12) | Diffuse (RGB) | 0x02 |
|
||
| B (+20..+28) | Ambient (RGB) | 0x01 |
|
||
| C (+36..+44) | Specular (RGB) | 0x04 |
|
||
| D (+52..+60) | Emissive (RGB) | 0x08 |
|
||
| (+32) | Specular power | 0x10 |
|
||
|
||
### Поле textureIndex (+68)
|
||
|
||
- Значение `< 0` означает «нет текстуры» → `texture_ptr = NULL`.
|
||
- Значение `≥ 0` используется как индекс в глобальном массиве текстурных объектов: `texture = texture_array[5 * textureIndex]`.
|
||
|
||
## 2.3. Алгоритм интерполяции материалов
|
||
|
||
Движок поддерживает **анимацию материалов** между ключевыми кадрами. Функция `sub_10003030`:
|
||
|
||
```
|
||
Вход: mat_a (исходный), mat_b (целевой), t (фактор 0..1), mask (битовая маска)
|
||
|
||
Выход: mat_result
|
||
|
||
Для каждого бита mask:
|
||
если бит установлен:
|
||
mat_result.component = mat_a.component + (mat_b.component - mat_a.component) × t
|
||
иначе:
|
||
mat_result.component = mat_a.component (без интерполяции)
|
||
|
||
mat_result.textureIndex = mat_a.textureIndex (всегда копируется без интерполяции)
|
||
```
|
||
|
||
### Режимы анимации материалов
|
||
|
||
Материал может иметь несколько фаз (phase) с разными режимами цикличности:
|
||
|
||
| Режим (flags & 7) | Описание |
|
||
|-------------------|-------------------------------------|
|
||
| 0 | Цикл: повтор с начала |
|
||
| 1 | Ping‑pong: туда‑обратно |
|
||
| 2 | Однократное воспроизведение (clamp) |
|
||
| 3 | Случайный кадр (random) |
|
||
|
||
## 2.4. Глобальный массив текстур
|
||
|
||
Текстуры хранятся в глобальном массиве записей по **20 байт** (5 DWORD):
|
||
|
||
```c
|
||
struct TextureSlot { // 20 байт
|
||
int32_t name_hash; // +0: Хэш/ID имени текстуры (-1 = свободен)
|
||
void* texture_object; // +4: Указатель на объект текстуры D3D
|
||
int32_t ref_count; // +8: Счётчик ссылок
|
||
uint32_t last_release; // +12: Время последнего Release
|
||
uint32_t extra; // +16: Дополнительный флаг
|
||
};
|
||
```
|
||
|
||
Функция `UnloadAllTextures` обнуляет все слоты, вызывая деструктор для каждого ненулевого `texture_object`.
|
||
|
||
## 2.5. Глобальный массив определений материалов
|
||
|
||
Определения материалов хранятся в глобальном массиве записей по **368 байт** (92 DWORD):
|
||
|
||
```c
|
||
struct MaterialDef { // 368 байт (92 DWORD)
|
||
int32_t name_hash; // dword_100669F0[92*i]: -1 = свободен
|
||
int32_t ref_count; // dword_100669F4[92*i]: Счётчик ссылок
|
||
int32_t phase_count; // dword_100669F8[92*i]: Число текстурных фаз
|
||
void* record_ptr; // dword_100669FC[92*i]: Указатель на массив записей по 76 байт
|
||
int32_t anim_phase_count; // dword_10066A00[92*i]: Число фаз анимации
|
||
// +20..+367: данные фаз анимации (до 22 фаз × 16 байт)
|
||
};
|
||
```
|
||
|
||
## 2.6. Переключатели рендера (из Ngi32.dll)
|
||
|
||
Движок читает настройки из реестра Windows (`HKCU\Software\Nikita\NgiTool`). Подтверждённые ключи:
|
||
|
||
| Ключ реестра | Глобальная переменная | Описание |
|
||
|--------------------------|-----------------------|---------------------------------|
|
||
| `Disable MultiTexturing` | `dword_1003A184` | Отключить мультитекстурирование |
|
||
| `DisableMipmap` | `dword_1003A174` | Отключить мипмап‑фильтрацию |
|
||
| `Force 16-bit textures` | `dword_1003A180` | Принудительно 16‑бит текстуры |
|
||
| `UseFirstCard` | `dword_100340EC` | Использовать первую видеокарту |
|
||
| `DisableD3DCalls` | `dword_1003A178` | Отключить вызовы D3D (отладка) |
|
||
| `DisableDSound` | `dword_1003A17C` | Отключить DirectSound |
|
||
| `ForceCpu` | (комбинированный) | Режим рендера: SW/HW TnL/Mixed |
|
||
|
||
### Значения ForceCpu и их влияние на рендер
|
||
|
||
| ForceCpu | Force SSE | Force 3DNow | Force FXCH | Force MMX |
|
||
|----------|-----------|-------------|------------|-----------|
|
||
| 2 | Да | Нет | Нет | Нет |
|
||
| 3 | Нет | Да | Нет | Нет |
|
||
| 4 | Да | Да | Нет | Нет |
|
||
| 5 | Да | Да | Да | Да |
|
||
| 6 | Да | Да | Да | Нет |
|
||
| 7 | Нет | Нет | Нет | Да |
|
||
|
||
### Практические выводы для порта
|
||
|
||
Движок спроектирован для работы **без** следующих функций (graceful degradation):
|
||
|
||
- Мипмапы.
|
||
- Bilinear/trilinear фильтрация.
|
||
- Мультитекстурирование (2‑й текстурный слой).
|
||
- 32‑битные текстуры (fallback на 16‑бит).
|
||
- Аппаратный T&L (software fallback).
|
||
|
||
---
|
||
|
||
## 2.7. Текстовый файл WEAR + LIGHTMAPS (World3D.dll)
|
||
|
||
`World3D.dll` содержит парсер текстового файла (режим `rt`), который задаёт:
|
||
|
||
- список **материалов (wear)**, используемых в сцене/объекте;
|
||
- список **лайтмап (lightmaps)**.
|
||
|
||
Формат читается через `fgets`/`sscanf`/`fscanf`, поэтому он чувствителен к структуре строк и ключевому слову `LIGHTMAPS`.
|
||
|
||
### 2.7.1. Блок WEAR (материалы)
|
||
|
||
1) **Первая строка файла** — целое число:
|
||
|
||
- `wearCount` (обязательно `> 0`, иначе ошибка `"Illegal wear length."`)
|
||
|
||
2) Далее следует `wearCount` строк. Каждая строка имеет вид:
|
||
|
||
- `<int> <пробелы> <materialName>`
|
||
|
||
Где:
|
||
|
||
- `<int>` парсится, но фактически не используется как ключ (движок обрабатывает записи последовательно).
|
||
- `<materialName>` — имя материала, которое движок ищет в менеджере материалов.
|
||
- Если материал не найден, пишется `"Material %s not found."` и используется fallback `"DEFAULT"`.
|
||
|
||
> Практическая рекомендация для инструментов: считайте `<int>` как необязательный “legacy-id”, а истинным идентификатором материала делайте строку `<materialName>`.
|
||
|
||
### 2.7.2. Блок LIGHTMAPS
|
||
|
||
После чтения wear-списка движок последовательно читает токены (`fscanf("%s")`) до тех пор, пока не встретит слово **`LIGHTMAPS`**.
|
||
|
||
Затем:
|
||
|
||
1) Читается `lightmapCount`:
|
||
|
||
- `lightmapCount` (обязательно `> 0`, иначе ошибка `"Illegal lightmaps length."`)
|
||
|
||
2) Далее следует `lightmapCount` строк вида:
|
||
|
||
- `<int> <пробелы> <lightmapName>`
|
||
|
||
Где:
|
||
|
||
- `<int>` парсится, но фактически не используется как ключ (аналогично wear).
|
||
- `<lightmapName>` — имя лайтмапы; если ресурс не найден, пишется `"LightMap %s not found."`.
|
||
|
||
### 2.7.3. Валидация имени лайтмапы (деталь движка)
|
||
|
||
Перед загрузкой лайтмапы выполняется проверка имени:
|
||
|
||
- в имени должна встречаться точка `.` **в пределах первых 16 символов**, иначе ошибка `"Bad texture name."`;
|
||
- далее движок использует подстроку после точки в вычислениях внутренних индексов/кэша (на практике полезно придерживаться шаблона вида `NAME.A1`, `NAME.B2` и т.п.).
|
||
|
||
---
|
||
## 2.8. Формат текстурного ассета `Texm` (Ngi32.dll)
|
||
|
||
Текстуры из `Textures.lib` хранятся как NRes‑entries типа `0x6D786554` (`"Texm"`).
|
||
|
||
### 2.8.1. Заголовок `Texm` (32 байта)
|
||
|
||
```c
|
||
struct TexmHeader32 {
|
||
uint32_t magic; // 0x6D786554 ('Texm')
|
||
uint32_t width; // base width
|
||
uint32_t height; // base height
|
||
uint32_t mipCount; // количество уровней
|
||
uint32_t flags4; // наблюдаются 0 или 32
|
||
uint32_t flags5; // наблюдаются 0 или 0x04000000
|
||
uint32_t unk6; // служебное поле (часто 0, иногда ненулевое)
|
||
uint32_t format; // код пиксельного формата
|
||
};
|
||
```
|
||
|
||
Подтверждённые `format`:
|
||
|
||
- `0` — paletted 8-bit (индекс + palette);
|
||
- `565`, `556`, `4444` — 16-bit семейство;
|
||
- `888`, `8888` — 32-bit семейство.
|
||
|
||
### 2.8.2. Layout payload
|
||
|
||
После заголовка:
|
||
|
||
1) если `format == 0`: palette блок 1024 байта (`256 × 4`);
|
||
2) далее mip-chain пикселей;
|
||
3) опционально chunk атласа `Page`.
|
||
|
||
Размер mip-chain:
|
||
|
||
```c
|
||
bytesPerPixel = (format == 0 ? 1 : format in {565,556,4444} ? 2 : 4);
|
||
pixelBytes = bytesPerPixel * sum_{i=0..mipCount-1}(max(1,width>>i) * max(1,height>>i));
|
||
```
|
||
|
||
Итого «чистый» размер без `Page`:
|
||
|
||
```c
|
||
sizeCore = 32 + (format == 0 ? 1024 : 0) + pixelBytes;
|
||
```
|
||
|
||
### 2.8.3. Опциональный `Page` chunk
|
||
|
||
Если после `sizeCore` остаются байты и в этой позиции стоит magic `"Page"` (`0x65676150`), парсер `sub_1000FF60` читает таблицу subrect:
|
||
|
||
```c
|
||
struct PageChunk {
|
||
uint32_t magic; // 'Page'
|
||
uint32_t count;
|
||
struct Rect16 {
|
||
int16_t x;
|
||
int16_t w;
|
||
int16_t y;
|
||
int16_t h;
|
||
} rects[count];
|
||
};
|
||
```
|
||
|
||
Для каждого rect рантайм строит:
|
||
|
||
- пиксельные границы (`x0,y0,x1,y1`);
|
||
- нормализованные UV (`u0,v0,u1,v1`) с делителем `1/(width<<mipSkip)` и `1/(height<<mipSkip)`.
|
||
|
||
`mipSkip` вычисляется `sub_1000F580` (уровень, с которого реально начинается загрузка в GPU в зависимости от формата/ограничений).
|
||
|
||
### 2.8.4. Palette в формате `format==0`
|
||
|
||
В `sub_1000FB30` palette конвертируется в локальную 32-bit таблицу; байты источника читаются как BGR-порядок (четвёртый байт входной записи не используется напрямую в базовом пути), итоговая alpha зависит от флагов runtime-конфига.
|
||
|
||
### 2.8.5. Проверка на реальных данных
|
||
|
||
Для всех 393 entries в `Textures.lib`:
|
||
|
||
- `magic == 'Texm'`;
|
||
- размеры совпадают с `sizeCore` либо `sizeCore + PageChunk (+pad до 8 байт NRes)`;
|
||
- при наличии хвоста в `sizeCore` всегда обнаруживается валидный `Page` chunk.
|
||
|
||
---
|