679 lines
24 KiB
Markdown
679 lines
24 KiB
Markdown
# MSH core
|
||
|
||
Документ фиксирует core-часть формата MSH на уровне, достаточном для:
|
||
|
||
- реализации runtime-совместимого движка (поведение 1:1);
|
||
- реализации reader/writer/editor/converter с lossless round-trip;
|
||
- валидации ассетов и диагностики повреждений.
|
||
|
||
Связанные документы:
|
||
|
||
- [NRes / RsLi](nres.md) — контейнер, каталог, атрибуты, выравнивание.
|
||
- [MSH animation](msh-animation.md) — детальная спецификация `Res8`/`Res19`.
|
||
- [Materials + Texm](materials-texm.md) — материальная часть и текстуры.
|
||
- [Terrain + map loading](terrain-map-loading.md) — отдельная ветка terrain-ресурсов.
|
||
|
||
---
|
||
|
||
## 1. Область и источники
|
||
|
||
### 1.1. Что покрывает этот документ
|
||
|
||
Этот документ покрывает именно **core-геометрию и её runtime-связи**:
|
||
|
||
- `Res1` (node table),
|
||
- `Res2` (header + slots),
|
||
- `Res3/4/5` (позиции/нормали/UV0),
|
||
- `Res6` (индексы),
|
||
- `Res7` (triangle descriptors),
|
||
- `Res10` (node string table),
|
||
- `Res13` (batch table),
|
||
- optional `Res15/16/18/20`,
|
||
- точки стыка с анимацией (`Res8/Res19`).
|
||
|
||
### 1.2. Что не покрывает
|
||
|
||
- детальную семантику материалов/текстурных фаз (см. `materials-texm.md`),
|
||
- terrain-ветку (`type 11/14/21` и связанные структуры, см. `terrain-map-loading.md`),
|
||
- полную математику анимационного сэмплирования (см. `msh-animation.md`).
|
||
|
||
### 1.3. Источники реверса
|
||
|
||
Основные подтверждения:
|
||
|
||
- `tmp/disassembler1/AniMesh.dll.c`:
|
||
- `sub_10015FD0` (загрузка ресурсов core-модели),
|
||
- `sub_100124D0` (поиск slot по node/lod/group),
|
||
- `sub_10012530` (доступ к строке узла в `Res10`),
|
||
- `sub_1000B2C0`/`sub_10013680` (tri/batch path),
|
||
- `sub_1000A460` (инициализация runtime-инстансов, копирование глобальных bounds).
|
||
- `tmp/disassembler2/AniMesh.dll.asm` — подтверждение смещений/stride/ветвлений.
|
||
- валидация corpus: `testdata/nres` (435 MSH моделей, нулевые ошибки в `tools/msh_doc_validator.py`).
|
||
|
||
---
|
||
|
||
## 2. Модель данных MSH (high-level)
|
||
|
||
MSH-модель — это NRes-контейнер, где ресурсы связаны **не по порядку, а по type-id**.
|
||
|
||
Базовая связь таблиц:
|
||
|
||
1. `Res1` для `(node, lod, group)` выбирает `slotIndex`.
|
||
2. `Res2.slot[slotIndex]` даёт диапазоны triangle/batch (`triStart/triCount`, `batchStart/batchCount`).
|
||
3. `Res13.batch` даёт `indexStart/indexCount/baseVertex`.
|
||
4. `Res6` даёт сырые `uint16` индексы.
|
||
5. `Res3/4/5` дают vertex-атрибуты по `baseVertex + index`.
|
||
|
||
Ключевая особенность runtime:
|
||
|
||
- скиннинг по узлам жёсткий (rigid attachment), без per-vertex bone weights в core-ресурсах.
|
||
|
||
---
|
||
|
||
## 3. Карта ресурсов и границы core
|
||
|
||
### 3.1. Ресурсы, которые читает core-loader (`sub_10015FD0`)
|
||
|
||
| Type | Ресурс | Статус в core-loader | Формат/stride |
|
||
|---:|---|---|---|
|
||
| 1 | Node table | required | 38 байт/узел (основной случай) |
|
||
| 2 | Model header + slots | required | `0x8C + slotCount*0x44` |
|
||
| 3 | Positions | required | 12 |
|
||
| 4 | Packed normals | обычно required | 4 |
|
||
| 5 | Packed UV0 | обычно required | 4 |
|
||
| 6 | Index buffer | required | 2 |
|
||
| 7 | Triangle descriptors | обычно required | 16 |
|
||
| 8 | Anim key pool | optional для статических | 24 |
|
||
| 10 | String table | обычно required | variable |
|
||
| 13 | Batch table | required | 20 |
|
||
| 15 | Доп. stream | optional | 8 |
|
||
| 16 | Tangent/bitangent stream | optional | 8 |
|
||
| 18 | Vertex color stream | optional | 4 |
|
||
| 19 | Anim mapping | optional для статических | 2 |
|
||
| 20 | Доп. таблица | optional | variable |
|
||
|
||
### 3.2. Ресурсы, которые встречаются в MSH, но вне этого документа
|
||
|
||
В corpus из 435 моделей стабильно встречаются также `type 9` и `type 17`.
|
||
Они **не загружаются** `sub_10015FD0` и относятся к некоревым подсистемам (материалы/эффекты/прочие runtime-ветки).
|
||
|
||
### 3.3. Прямая MSH и вложенная MSH
|
||
|
||
Tooling должен поддерживать два режима входа:
|
||
|
||
- файл уже является модельным NRes (`magic NRes` и содержит `type 1/2/3/6/13`),
|
||
- файл-архив содержит `.msh` entry, внутри которой вложенный NRes модели.
|
||
|
||
---
|
||
|
||
## 4. Runtime-контракт загрузки (`sub_10015FD0`)
|
||
|
||
`sub_10015FD0` заполняет структуру модели размером `0xA4` байт и строит derived pointers/stride.
|
||
|
||
### 4.1. Порядок `find/open`
|
||
|
||
Фактический порядок загрузки:
|
||
|
||
1. `type 1 -> this+0x00`
|
||
2. `type 2 -> this+0x04`
|
||
3. `type 3 -> this+0x0C`
|
||
4. `type 4 -> this+0x10`
|
||
5. `type 5 -> this+0x14`
|
||
6. `type 10 -> this+0x20`
|
||
7. `type 8 -> this+0x18`
|
||
8. `type 19 -> this+0x1C`
|
||
9. `type 7 -> this+0x24`
|
||
10. `type 13 -> this+0x28`
|
||
11. `type 6 -> this+0x2C`
|
||
12. `type 15 -> this+0x34`
|
||
13. `type 16 -> this+0x38`
|
||
14. `type 18 -> this+0x64` (через отдельный `find`, optional)
|
||
15. `type 20 -> this+0x30` (optional)
|
||
|
||
### 4.2. Derived-поля (стримы)
|
||
|
||
После загрузки ставятся derived-поля:
|
||
|
||
- `this+0x08 = Res2 + 0x8C` (начало slot table),
|
||
- `this+0x3C = Res3`, `this+0x40 = 12`,
|
||
- `this+0x44 = Res4`, `this+0x48 = 4`,
|
||
- `this+0x5C = Res5`, `this+0x60 = 4`,
|
||
- `this+0x8C = Res15`, `this+0x90 = 8`,
|
||
- `this+0x94 = 0` (инициализация нулём).
|
||
|
||
Для `Res16`:
|
||
|
||
- если есть: `this+0x4C = Res16`, `this+0x50 = 8`, `this+0x54 = Res16+4`, `this+0x58 = 8`;
|
||
- если нет: `this+0x4C = 0`, `this+0x54 = 0` (stride остаются несущественными, т.к. указатели нулевые).
|
||
|
||
Для `Res18`:
|
||
|
||
- если найден: `this+0x64 = ptr`, `this+0x68 = 4`;
|
||
- иначе: `this+0x64 = 0`, `this+0x68 = 0`.
|
||
|
||
### 4.3. Метаданные из каталога NRes
|
||
|
||
- `this+0x9C` получает `entry(type19).attr2` (читается из поля `+8` каталожной записи, индекс `entry * 64`).
|
||
- `this+0xA0` получает `entry(type20).attr1` (поле `+4`) только если `type20` существует и успешно открыт; иначе `0`.
|
||
|
||
---
|
||
|
||
## 5. Бинарные структуры core-ресурсов
|
||
|
||
Все структуры little-endian.
|
||
|
||
### 5.1. `Res1` — Node table
|
||
|
||
Базовый stride: `38` байт (`19 * uint16`).
|
||
|
||
```c
|
||
struct Node38 {
|
||
uint16_t hdr0; // +0
|
||
uint16_t hdr1; // +2
|
||
uint16_t hdr2; // +4
|
||
uint16_t hdr3; // +6
|
||
uint16_t slotIndex[15]; // +8: [lod0 g0..g4][lod1 g0..g4][lod2 g0..g4]
|
||
};
|
||
```
|
||
|
||
#### Подтверждённые поля
|
||
|
||
- `hdr1`: parent/index-link (используется при построении инстанса), `0xFFFF` = нет.
|
||
- `hdr2`: `mapStart` для `Res19` (см. `msh-animation.md`), `0xFFFF` = нет map.
|
||
- `hdr3`: fallback key index в `Res8`.
|
||
- `hdr0`: node flags (есть битовые проверки, но полная доменная семантика не закрыта).
|
||
|
||
#### Адресация slot (runtime-функция `sub_100124D0`)
|
||
|
||
```c
|
||
uint16_t get_slot_index(const Node38* node_table, uint32_t nodeIndex, int lod, int group, int current_lod) {
|
||
int use_lod = (lod == -1) ? current_lod : lod;
|
||
int word_index = 4 + (int)nodeIndex * 19 + use_lod * 5 + group;
|
||
return *(uint16_t*)((const uint8_t*)node_table + word_index * 2);
|
||
}
|
||
```
|
||
|
||
`0xFFFF` означает "слот отсутствует".
|
||
|
||
#### Вариант stride=24
|
||
|
||
В corpus есть единичный служебный outlier с `Res1.attr3 = 24`.
|
||
Для 1:1 editing существующих ассетов требуется copy-through этого варианта.
|
||
Новая генерация должна ориентироваться на stride `38`, если нет чёткой цели поддержать legacy-вариант.
|
||
|
||
---
|
||
|
||
### 5.2. `Res2` — Model header + Slot table
|
||
|
||
```
|
||
Res2:
|
||
[0x00 .. 0x8B] model header (140 bytes)
|
||
[0x8C .. end] slot records (68 bytes each)
|
||
```
|
||
|
||
#### 5.2.1. Header (0x8C)
|
||
|
||
Runtime копирует блоки как float-массивы:
|
||
|
||
- `0x00..0x5F` (`24 float`) — глобальный hull (`vec3[8]`),
|
||
- `0x60..0x6F` (`4 float`) — глобальная sphere (`center.xyz + radius`),
|
||
- `0x70..0x8B` (`7 float`) — сегмент/капсула (`A.xyz`, `B.xyz`, `radius`).
|
||
|
||
#### 5.2.2. Slot record (68 bytes)
|
||
|
||
```c
|
||
struct Slot68 {
|
||
uint16_t triStart; // +0
|
||
uint16_t triCount; // +2
|
||
uint16_t batchStart; // +4
|
||
uint16_t batchCount; // +6
|
||
|
||
float aabbMin[3]; // +8
|
||
float aabbMax[3]; // +20
|
||
float sphereCenter[3]; // +32
|
||
float sphereRadius; // +44
|
||
|
||
uint32_t unk30; // +48
|
||
uint32_t unk34; // +52
|
||
uint32_t unk38; // +56
|
||
uint32_t unk3C; // +60
|
||
uint32_t unk40; // +64
|
||
};
|
||
```
|
||
|
||
`triCount` подтверждён как длина диапазона:
|
||
|
||
```c
|
||
triId >= triStart && triId < triStart + triCount
|
||
```
|
||
|
||
Хвост `unk30..unk40` должен сохраняться без изменений в editor/writer.
|
||
|
||
#### 5.2.3. Bounds semantics
|
||
|
||
- Slot bounds локальны относительно узла.
|
||
- При world-трансформации sphere radius масштабируется по `max(scaleX, scaleY, scaleZ)` при неравномерном scale.
|
||
|
||
---
|
||
|
||
### 5.3. `Res3` — Positions
|
||
|
||
```c
|
||
struct Position12 {
|
||
float x;
|
||
float y;
|
||
float z;
|
||
};
|
||
```
|
||
|
||
Stride `12`.
|
||
|
||
---
|
||
|
||
### 5.4. `Res4` — Packed normals
|
||
|
||
```c
|
||
struct PackedNormal4 {
|
||
int8_t nx;
|
||
int8_t ny;
|
||
int8_t nz;
|
||
int8_t nw; // семантика 4-го байта не зафиксирована
|
||
};
|
||
```
|
||
|
||
Декодирование:
|
||
|
||
```c
|
||
normal = clamp((float)n / 127.0f, -1.0f, 1.0f)
|
||
```
|
||
|
||
- делитель строго `127.0`;
|
||
- clamp обязателен из-за `-128 / 127.0`.
|
||
|
||
Кодирование (writer):
|
||
|
||
```c
|
||
int8_t q = (int8_t)clamp(round(v * 127.0f), -128, 127);
|
||
```
|
||
|
||
---
|
||
|
||
### 5.5. `Res5` — Packed UV0
|
||
|
||
```c
|
||
struct PackedUV4 {
|
||
int16_t u;
|
||
int16_t v;
|
||
};
|
||
```
|
||
|
||
Декодирование:
|
||
|
||
```c
|
||
uv = packed / 1024.0f
|
||
```
|
||
|
||
Кодирование:
|
||
|
||
```c
|
||
int16_t q = (int16_t)clamp(round(uv * 1024.0f), -32768, 32767);
|
||
```
|
||
|
||
---
|
||
|
||
### 5.6. `Res6` — Index buffer
|
||
|
||
Массив `uint16`, stride `2`.
|
||
|
||
Runtime-путь:
|
||
|
||
```c
|
||
vertexIndex = Res6[indexStart + i] + batch.baseVertex;
|
||
```
|
||
|
||
`indexStart` хранится в элементах, не в байтах.
|
||
|
||
---
|
||
|
||
### 5.7. `Res7` — Triangle descriptors (16 bytes)
|
||
|
||
```c
|
||
struct TriDesc16 {
|
||
uint16_t triFlags; // +0
|
||
uint16_t linkTri0; // +2
|
||
uint16_t linkTri1; // +4
|
||
uint16_t linkTri2; // +6
|
||
int16_t nX; // +8
|
||
int16_t nY; // +10
|
||
int16_t nZ; // +12
|
||
uint16_t selPacked; // +14
|
||
};
|
||
```
|
||
|
||
- `nX/nY/nZ` декодируются через `1/32767`.
|
||
- `linkTri*` используются в tri-neighbour/collision path.
|
||
|
||
Раскладка `selPacked` (3 селектора по 2 бита):
|
||
|
||
```c
|
||
sel0 = (selPacked >> 0) & 0x3; if (sel0 == 3) sel0 = 0xFFFF;
|
||
sel1 = (selPacked >> 2) & 0x3; if (sel1 == 3) sel1 = 0xFFFF;
|
||
sel2 = (selPacked >> 4) & 0x3; if (sel2 == 3) sel2 = 0xFFFF;
|
||
```
|
||
|
||
---
|
||
|
||
### 5.8. `Res13` — Batch table (20 bytes)
|
||
|
||
```c
|
||
struct Batch20 {
|
||
uint16_t batchFlags; // +0
|
||
uint16_t materialIndex; // +2
|
||
uint16_t unk4; // +4
|
||
uint16_t unk6; // +6
|
||
uint16_t indexCount; // +8
|
||
uint32_t indexStart; // +10
|
||
uint16_t unk14; // +14
|
||
uint32_t baseVertex; // +16
|
||
};
|
||
```
|
||
|
||
`unk4/unk6/unk14` семантически не закрыты; writer/editor должны сохранять.
|
||
|
||
---
|
||
|
||
### 5.9. `Res10` — Node string table
|
||
|
||
Последовательность записей variable-length:
|
||
|
||
```c
|
||
struct Res10Record {
|
||
uint32_t len; // длина строки без '\0'
|
||
char text[]; // если len>0: len+1 байт (с '\0'), иначе payload нет
|
||
};
|
||
```
|
||
|
||
Переход:
|
||
|
||
```c
|
||
next = cur + 4 + (len ? len + 1 : 0);
|
||
```
|
||
|
||
`sub_10012530` возвращает:
|
||
|
||
- `NULL`, если `len == 0`,
|
||
- `record + 4`, если `len > 0`.
|
||
|
||
Индекс записи в `Res10` соответствует `nodeIndex`.
|
||
|
||
---
|
||
|
||
### 5.10. Optional streams
|
||
|
||
#### `Res15` (stride 8)
|
||
|
||
Дополнительный поток на вершину (семантика не полностью подтверждена).
|
||
|
||
#### `Res16` (stride 8, split 2x4)
|
||
|
||
Runtime делит поток на два interleaved подпотока:
|
||
|
||
- stream A: `base+0`, stride 8,
|
||
- stream B: `base+4`, stride 8.
|
||
|
||
В corpus из `testdata/nres` этот ресурс не встретился, но loader поддерживает.
|
||
|
||
#### `Res18` (stride 4)
|
||
|
||
Vertex color / доп. packed-канал. В corpus встречается на части моделей.
|
||
|
||
#### `Res20`
|
||
|
||
Доп. таблица неизвестной доменной семантики. Loader хранит pointer и метаданные каталога (`attr1`).
|
||
|
||
---
|
||
|
||
### 5.11. Точки стыка с анимацией (`Res8`/`Res19`)
|
||
|
||
Core-loader загружает:
|
||
|
||
- `Res8` в `this+0x18`,
|
||
- `Res19` в `this+0x1C`,
|
||
- `Res19.attr2` в `this+0x9C`.
|
||
|
||
Полный runtime-алгоритм сэмплирования/смешивания описан в [MSH animation](msh-animation.md).
|
||
|
||
---
|
||
|
||
## 6. Runtime-алгоритмы core
|
||
|
||
### 6.1. Slot lookup (`sub_100124D0`)
|
||
|
||
Вход: runtime-node-instance, `group`, `lod`.
|
||
|
||
1. Если нет model pointer -> `NULL`.
|
||
2. `lod == -1` -> подставить `current_lod` инстанса.
|
||
3. Вычислить `slotIndex` через формулу `4 + node*19 + lod*5 + group`.
|
||
4. Если `slotIndex == 0xFFFF` -> `NULL`.
|
||
5. Иначе вернуть `Res2.slotBase + slotIndex * 68`.
|
||
|
||
### 6.2. Node string lookup (`sub_10012530`)
|
||
|
||
1. Идти по `Res10`-записям `nodeIndex` раз.
|
||
2. Возвращать `NULL` или `char*` по правилу `len==0`.
|
||
|
||
### 6.3. Геометрический обход для рендера
|
||
|
||
Reference-путь, эквивалентный runtime-логике:
|
||
|
||
```c
|
||
for each node:
|
||
slot = resolve_slot(node, lod, group)
|
||
if (!slot) continue
|
||
|
||
for b in [slot.batchStart .. slot.batchStart + slot.batchCount):
|
||
batch = Res13[b]
|
||
for i in [0 .. batch.indexCount):
|
||
idx = Res6[batch.indexStart + i]
|
||
vtx = batch.baseVertex + idx
|
||
|
||
pos = Res3[vtx]
|
||
nrm = decode_res4(Res4[vtx])
|
||
uv0 = decode_res5(Res5[vtx])
|
||
```
|
||
|
||
### 6.4. Tri/collision path (обобщённо)
|
||
|
||
- `sub_1000B2C0` и `sub_10013680` используют tri-диапазоны слота + `Res7` link/select-поля.
|
||
- Для collision/picking-контекста должны быть валидны:
|
||
- `slot.triStart + slot.triCount <= triDescCount`,
|
||
- `linkTri*` либо `0xFFFF`, либо `< triDescCount`.
|
||
|
||
---
|
||
|
||
## 7. Инварианты и валидация (reader)
|
||
|
||
### 7.1. Базовые проверки целостности
|
||
|
||
- каждый fixed-stride ресурс делится на stride без остатка;
|
||
- `Res2.size >= 0x8C`;
|
||
- `(Res2.size - 0x8C) % 68 == 0`;
|
||
- `Res2.attr1 == slotCount`, `Res2.attr3 == 68`;
|
||
- `Res3.attr3 == 12`, `Res4.attr3 == 4`, `Res5.attr3 == 4`, `Res6.attr3 == 2`, `Res7.attr3 == 16`, `Res13.attr3 == 20`;
|
||
- `Res8.attr3 == 4` (не stride), `Res19.attr3 == 2`, `Res10.attr3 == 0` (в observed assets).
|
||
|
||
### 7.2. Cross-table проверки
|
||
|
||
- `slot.batchStart + slot.batchCount <= batchCount`;
|
||
- `slot.triStart + slot.triCount <= triDescCount`;
|
||
- `batch.indexStart + batch.indexCount <= indexCount`;
|
||
- `batch.baseVertex + max(indexSlice) < vertexCount`;
|
||
- все `Res1.slotIndex[*]` либо `0xFFFF`, либо `< slotCount`;
|
||
- для `Res10`: парсинг ровно `nodeCount` записей без хвостовых байт;
|
||
- для `Res7.linkTri*`: либо `0xFFFF`, либо `< triDescCount`.
|
||
|
||
### 7.3. Strict vs tolerant режим
|
||
|
||
Рекомендуется 2 режима reader:
|
||
|
||
- `strict`: любое нарушение инвариантов -> ошибка;
|
||
- `tolerant`: безопасно отбрасывать/игнорировать только локально повреждённые диапазоны (без OOB).
|
||
|
||
---
|
||
|
||
## 8. Правила writer/editor
|
||
|
||
### 8.1. Обязательная политика для 1:1 editing
|
||
|
||
- сохранять неизвестные поля (`Slot68.unk*`, `Batch20.unk*`, `Node.hdr0` и т.д.) без модификации, если нет осознанного пересчёта;
|
||
- сохранять неизвестные resource types и их payload/атрибуты;
|
||
- не полагаться на порядок ресурсов в контейнере: lookup в runtime идёт по type-id.
|
||
|
||
### 8.2. Пересчёт атрибутов каталога
|
||
|
||
При записи изменённых ресурсов:
|
||
|
||
- `attr1` = count (или форматно-специфичное значение),
|
||
- `attr2` — по формату/семантике ресурса,
|
||
- `attr3` — stride/константа формата.
|
||
|
||
Практические правила для core:
|
||
|
||
- `Res1`: `attr1=nodeCount`, `attr3=38` (или исходный вариант, если copy-through legacy), `attr2` лучше сохранять из исходника;
|
||
- `Res2`: `attr1=slotCount`, `attr2=0`, `attr3=68`;
|
||
- `Res3/4/5/6/7/13/15/16/18`: `attr1=size/stride`, `attr2=0`, `attr3=stride`;
|
||
- `Res8`: `attr1=size/24`, `attr3=4`;
|
||
- `Res10`: `attr1=nodeCount`, `attr2=0`, `attr3=0`;
|
||
- `Res19`: `attr1=size/2`, `attr2=frameCount`, `attr3=2`.
|
||
|
||
### 8.3. Матрица зависимостей при редактировании
|
||
|
||
| Операция | Какие ресурсы обновлять |
|
||
|---|---|
|
||
| Смещение/деформация вершин | `Res3`, при необходимости `Res4`, bounds в `Res2` |
|
||
| Изменение UV | `Res5` (и опционально `Res15`) |
|
||
| Изменение topology (индексы/треугольники) | `Res6`, `Res13`, `Res7`, диапазоны `Res2.slot` |
|
||
| Изменение LOD/group назначения | `Res1.slotIndex`, возможно `Res2.slot` |
|
||
| Изменение имени узла | `Res10` |
|
||
| Изменение иерархии/анимации узлов | `Res1.hdr1/hdr2/hdr3`, `Res8`, `Res19` |
|
||
| Добавление/удаление slot | `Res2`, ссылки из `Res1`, диапазоны batch/tri |
|
||
|
||
### 8.4. Детерминированная сериализация
|
||
|
||
- little-endian для всех чисел;
|
||
- без внутреннего padding в таблицах ресурсов;
|
||
- выравнивание блоков ресурсов в NRes по 8 байт (через контейнер).
|
||
|
||
---
|
||
|
||
## 9. Рекомендованный canonical IR для toolchain
|
||
|
||
Минимальный IR для безопасного round-trip:
|
||
|
||
```c
|
||
struct ModelCoreIR {
|
||
// raw payloads for unknown/passthrough types
|
||
map<uint32_t, RawResource> raw_passthrough;
|
||
|
||
vector<Node> nodes; // Res1 decoded (hdr + matrix)
|
||
Header140 header; // Res2[0x00..0x8B]
|
||
vector<Slot> slots; // Res2 slot table (включая unk tail)
|
||
|
||
vector<float3> positions; // Res3
|
||
vector<PackedNormal4> normals_raw; // Res4 raw + optional decoded cache
|
||
vector<PackedUV4> uv0_raw; // Res5 raw + optional decoded cache
|
||
|
||
vector<uint16_t> indices; // Res6
|
||
vector<TriDesc16> tri; // Res7
|
||
vector<Batch20> batches; // Res13
|
||
vector<optional<string>> node_names; // Res10
|
||
|
||
optional<vector<uint8_t>> res15_raw;
|
||
optional<vector<uint8_t>> res16_raw;
|
||
optional<vector<uint32_t>> colors_raw; // Res18
|
||
optional<RawResource> res20_raw;
|
||
|
||
// animation bridge
|
||
optional<vector<AnimKey24>> anim_keys; // Res8
|
||
optional<vector<uint16_t>> anim_map_words; // Res19
|
||
uint32_t anim_frame_count;
|
||
};
|
||
```
|
||
|
||
Принцип: где семантика неполная, хранить raw и переизлучать байт-в-байт.
|
||
|
||
---
|
||
|
||
## 10. Практика конвертации
|
||
|
||
### 10.1. MSH -> OBJ/GLTF
|
||
|
||
- `Res3` напрямую в позиции;
|
||
- `Res6 + Res13` в faces;
|
||
- нормали/UV декодировать через коэффициенты `1/127`, `1/1024`;
|
||
- при экспорте по LOD/group использовать `Res1` матрицу слотов, а не "все batch подряд" (если нужен runtime-эквивалент);
|
||
- пометить ограничения: core не содержит классический weight-скиннинг.
|
||
|
||
### 10.2. Обратный импорт (OBJ/GLTF -> MSH)
|
||
|
||
Для 1:1 ожидаемого поведения импортёр должен:
|
||
|
||
- строить корректные `Res13` диапазоны,
|
||
- строить/обновлять `Res2.slot` ranges и bounds,
|
||
- поддерживать quantization при упаковке (`Res4/Res5`),
|
||
- сохранять unknown-поля таблиц, если вход был редактированием существующей модели.
|
||
|
||
---
|
||
|
||
## 11. Наблюдения по corpus (testdata/nres)
|
||
|
||
Сводка по 435 MSH-моделям:
|
||
|
||
- валидны все 435/435 по `tools/msh_doc_validator.py`;
|
||
- основной порядок типов:
|
||
- `414`: `(1,2,3,4,5,15,13,6,7,8,19,9,10,17)`
|
||
- `21`: `(1,2,3,4,5,18,15,13,6,7,8,19,9,10,17,20)`
|
||
- `Res1.attr3`: `38` в 434 моделях, `24` в 1 модели;
|
||
- `Res18` и `Res20` встречаются в 21 модели;
|
||
- `Res16` в данном corpus не встретился;
|
||
- `Res8/Res19` присутствуют во всех моделях, но `Res19.attr2=1` часто соответствует статике.
|
||
|
||
---
|
||
|
||
## 12. Открытые вопросы (не блокируют 1:1)
|
||
|
||
- точная доменная семантика `Node.hdr0` битов;
|
||
- полные имена/назначения `Batch20.unk4/unk6/unk14`;
|
||
- назначение `Slot68.unk30..unk40`;
|
||
- полная семантика `Res15/Res16/Res18/Res20` payload beyond stride-level;
|
||
- точная семантика 4-го байта в `PackedNormal4`.
|
||
|
||
Для runtime/reader/writer это не критично при условии byte-preserving policy.
|
||
|
||
---
|
||
|
||
## 13. Чеклист реализации 1:1
|
||
|
||
### 13.1. Engine runtime
|
||
|
||
- реализован loader-порядок как в `sub_10015FD0`;
|
||
- slot lookup по формуле `4 + node*19 + lod*5 + group`;
|
||
- декодирование `Res4` через `/127.0` с clamp;
|
||
- декодирование `Res5` через `/1024.0`;
|
||
- tri селекторы `selPacked` трактуются как 2-битные с `3 -> 0xFFFF`;
|
||
- корректная обработка `0xFFFF` sentinel во всех таблицах.
|
||
|
||
### 13.2. Reader/validator
|
||
|
||
- строгая проверка stride/размеров/диапазонов;
|
||
- OOB-защита всех индексных доступов;
|
||
- поддержка both direct-model и nested `.msh` payload.
|
||
|
||
### 13.3. Writer/editor
|
||
|
||
- стабильный пересчёт `attr1/attr2/attr3`;
|
||
- сохранение unknown fields и unknown resource types;
|
||
- детерминированная сериализация NRes (8-byte align);
|
||
- regression-проверка round-trip: `decode -> encode -> decode` без расхождений структуры/диапазонов.
|
||
|