# 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.

---