Документирование и обновление спецификаций
- Обновлены спецификации `runtime-pipeline`, `sound`, `terrain-map-loading`, `texture`, `ui` и `wear`. - Добавлены разделы о статусе покрытия и оставшихся задачах для достижения 100% завершенности. - Внесены уточнения по архитектурным ролям, минимальным контрактам и требованиям к toolchain для каждой подсистемы. - Уточнены форматы данных и правила взаимодействия между компонентами системы.
This commit is contained in:
@@ -1,277 +1,118 @@
|
||||
# 3D implementation notes
|
||||
|
||||
Контрольные заметки, сводки алгоритмов и остаточные семантические вопросы по 3D-подсистемам.
|
||||
Контрольная страница с практическими правилами реализации 3D-пайплайна и с перечнем незакрытых зон.
|
||||
Документ intentionally high-level: без ссылок на внутренние функции/адреса.
|
||||
|
||||
---
|
||||
Связанные страницы:
|
||||
|
||||
## 5.1. Порядок байт
|
||||
- [MSH core](msh-core.md)
|
||||
- [MSH animation](msh-animation.md)
|
||||
- [Material (`MAT0`)](material.md)
|
||||
- [Texture (`Texm`)](texture.md)
|
||||
- [FXID](fxid.md)
|
||||
- [Render pipeline](render.md)
|
||||
|
||||
Все значения хранятся в **little‑endian** порядке (платформа x86/Win32).
|
||||
## 1. Базовые двоичные правила
|
||||
|
||||
## 5.2. Выравнивание
|
||||
1. Все форматы в этой подсистеме little-endian.
|
||||
2. Внутри NRes данные ресурсов выравниваются по 8 байт.
|
||||
3. Внутри payload таблиц padding между записями обычно отсутствует: записи идут подряд по stride.
|
||||
|
||||
- **NRes‑ресурсы:** данные каждого ресурса внутри NRes‑архива выровнены по границе **8 байт** (0‑padding).
|
||||
- **Внутренняя структура ресурсов:** таблицы Res1/Res2/Res7/Res13 не имеют межзаписевого выравнивания — записи идут подряд.
|
||||
- **Vertex streams:** stride'ы фиксированы (12/4/8 байт) — вершинные данные идут подряд без паддинга.
|
||||
## 2. Быстрая карта stride'ов
|
||||
|
||||
## 5.3. Размеры записей на диске
|
||||
| Ресурс | Запись | Stride |
|
||||
|---|---|---:|
|
||||
| Res1 | Node | 38 |
|
||||
| Res2 | Slot | 68 (после header `0x8C`) |
|
||||
| Res3 | Position | 12 |
|
||||
| Res4 | Normal | 4 |
|
||||
| Res5 | UV0 | 4 |
|
||||
| Res6 | Index | 2 |
|
||||
| Res7 | Tri descriptor | 16 |
|
||||
| Res8 | Animation key | 24 |
|
||||
| Res13 | Batch | 20 |
|
||||
| Res19 | Animation map | 2 |
|
||||
|
||||
| Ресурс | Запись | Размер (байт) | Stride |
|
||||
|--------|-----------|---------------|-------------------------|
|
||||
| Res1 | Node | 38 | 38 (19×u16) |
|
||||
| Res2 | Slot | 68 | 68 |
|
||||
| Res3 | Position | 12 | 12 (3×f32) |
|
||||
| Res4 | Normal | 4 | 4 (4×s8) |
|
||||
| Res5 | UV0 | 4 | 4 (2×s16) |
|
||||
| Res6 | Index | 2 | 2 (u16) |
|
||||
| Res7 | TriDesc | 16 | 16 |
|
||||
| Res8 | AnimKey | 24 | 24 |
|
||||
| Res10 | StringRec | переменный | `4 + (len ? len+1 : 0)` |
|
||||
| Res13 | Batch | 20 | 20 |
|
||||
| Res19 | AnimMap | 2 | 2 (u16) |
|
||||
| Res15 | VtxStr | 8 | 8 |
|
||||
| Res16 | VtxStr | 8 | 8 (2×4) |
|
||||
| Res18 | VtxStr | 4 | 4 |
|
||||
## 3. Декодирование ключевых потоков
|
||||
|
||||
## 5.4. Вычисление количества элементов
|
||||
## 3.1. Позиции (Res3)
|
||||
|
||||
Количество записей вычисляется из размера ресурса:
|
||||
`float3`, stride `12`.
|
||||
|
||||
```
|
||||
count = resource_data_size / record_stride
|
||||
## 3.2. Нормали (Res4)
|
||||
|
||||
`int8[4]`, используются первые 3 компоненты:
|
||||
|
||||
```text
|
||||
n = clamp(s8 / 127.0, -1..1)
|
||||
```
|
||||
|
||||
Например:
|
||||
## 3.3. UV (Res5)
|
||||
|
||||
- `vertex_count = res3_size / 12`
|
||||
- `index_count = res6_size / 2`
|
||||
- `batch_count = res13_size / 20`
|
||||
- `slot_count = (res2_size - 140) / 68`
|
||||
- `node_count = res1_size / 38`
|
||||
- `tri_desc_count = res7_size / 16`
|
||||
- `anim_key_count = res8_size / 24`
|
||||
- `anim_map_count = res19_size / 2`
|
||||
`int16[2]`:
|
||||
|
||||
Для Res10 нет фиксированного stride: нужно последовательно проходить записи `u32 len` + `(len ? len+1 : 0)` байт.
|
||||
|
||||
## 5.5. Идентификация ресурсов в NRes
|
||||
|
||||
Ресурсы модели идентифицируются по полю `type` (смещение 0) в каталожной записи NRes. Загрузчик использует `niFindRes(archive, type, subtype)` для поиска, где `type` — число (1, 2, 3, ... 20), а `subtype` (byte) — уточнение (из аргумента загрузчика).
|
||||
|
||||
## 5.6. Минимальный набор для рендера
|
||||
|
||||
Для статической модели без анимации достаточно:
|
||||
|
||||
| Ресурс | Обязательность |
|
||||
|--------|------------------------------------------------|
|
||||
| Res1 | Да |
|
||||
| Res2 | Да |
|
||||
| Res3 | Да |
|
||||
| Res4 | Рекомендуется |
|
||||
| Res5 | Рекомендуется |
|
||||
| Res6 | Да |
|
||||
| Res7 | Для коллизии |
|
||||
| Res13 | Да |
|
||||
| Res10 | Желательно (узловые имена/поведенческие ветки) |
|
||||
| Res8 | Нет (анимация) |
|
||||
| Res19 | Нет (анимация) |
|
||||
| Res15 | Нет |
|
||||
| Res16 | Нет |
|
||||
| Res18 | Нет |
|
||||
| Res20 | Нет |
|
||||
|
||||
## 5.7. Сводка алгоритмов декодирования
|
||||
|
||||
### Позиции (Res3)
|
||||
|
||||
```python
|
||||
def decode_position(data, vertex_index):
|
||||
offset = vertex_index * 12
|
||||
x = struct.unpack_from('<f', data, offset)[0]
|
||||
y = struct.unpack_from('<f', data, offset + 4)[0]
|
||||
z = struct.unpack_from('<f', data, offset + 8)[0]
|
||||
return (x, y, z)
|
||||
```text
|
||||
u = s16 / 1024.0
|
||||
v = s16 / 1024.0
|
||||
```
|
||||
|
||||
### Нормали (Res4)
|
||||
## 3.4. Animation key (Res8)
|
||||
|
||||
```python
|
||||
def decode_normal(data, vertex_index):
|
||||
offset = vertex_index * 4
|
||||
nx = struct.unpack_from('<b', data, offset)[0] # int8
|
||||
ny = struct.unpack_from('<b', data, offset + 1)[0]
|
||||
nz = struct.unpack_from('<b', data, offset + 2)[0]
|
||||
# nw = data[offset + 3] # не используется
|
||||
return (
|
||||
max(-1.0, min(1.0, nx / 127.0)),
|
||||
max(-1.0, min(1.0, ny / 127.0)),
|
||||
max(-1.0, min(1.0, nz / 127.0)),
|
||||
)
|
||||
`pos(float3) + time(float) + quat(int16x4)`:
|
||||
|
||||
```text
|
||||
q = s16 / 32767.0
|
||||
```
|
||||
|
||||
### UV‑координаты (Res5)
|
||||
## 4. Практический reader-контракт
|
||||
|
||||
```python
|
||||
def decode_uv(data, vertex_index):
|
||||
offset = vertex_index * 4
|
||||
u = struct.unpack_from('<h', data, offset)[0] # int16
|
||||
v = struct.unpack_from('<h', data, offset + 2)[0]
|
||||
return (u / 1024.0, v / 1024.0)
|
||||
```
|
||||
Для runtime-совместимого чтения модели:
|
||||
|
||||
### Кодирование нормали (для экспортёра)
|
||||
1. Найти нужные ресурсы по `type_id` в NRes.
|
||||
2. Проверить `size/stride`-инварианты.
|
||||
3. Проверить диапазоны ссылок:
|
||||
- slot -> batch/triangles;
|
||||
- batch -> indices;
|
||||
- indices -> vertices;
|
||||
- anim_map -> anim_keys.
|
||||
4. Неизвестные поля и неизвестные ресурсы сохранять через copy-through.
|
||||
|
||||
```python
|
||||
def encode_normal(nx, ny, nz):
|
||||
return (
|
||||
max(-128, min(127, int(round(nx * 127.0)))),
|
||||
max(-128, min(127, int(round(ny * 127.0)))),
|
||||
max(-128, min(127, int(round(nz * 127.0)))),
|
||||
0 # nw = 0 (безопасное значение)
|
||||
)
|
||||
```
|
||||
## 5. Практический writer-контракт
|
||||
|
||||
### Кодирование UV (для экспортёра)
|
||||
1. Пересчитывать только явно вычислимые поля.
|
||||
2. Не нормализовать opaque-данные без уверенной спецификации.
|
||||
3. При roundtrip неизмененных данных требовать byte-identical результат.
|
||||
4. Для новых ассетов фиксировать отдельную политику «генерация vs preserve».
|
||||
|
||||
```python
|
||||
def encode_uv(u, v):
|
||||
return (
|
||||
max(-32768, min(32767, int(round(u * 1024.0)))),
|
||||
max(-32768, min(32767, int(round(v * 1024.0))))
|
||||
)
|
||||
```
|
||||
## 6. Runtime-связка материалов и текстур
|
||||
|
||||
### Строки узлов (Res10)
|
||||
Канонический путь резолва:
|
||||
|
||||
```python
|
||||
def parse_res10_for_nodes(buf: bytes, node_count: int) -> list[str | None]:
|
||||
out = []
|
||||
off = 0
|
||||
for _ in range(node_count):
|
||||
ln = struct.unpack_from('<I', buf, off)[0]
|
||||
off += 4
|
||||
if ln == 0:
|
||||
out.append(None)
|
||||
continue
|
||||
raw = buf[off:off + ln + 1] # len + '\0'
|
||||
out.append(raw[:-1].decode('ascii', errors='replace'))
|
||||
off += ln + 1
|
||||
return out
|
||||
```
|
||||
1. Модель -> wear-таблица (`*.wea`).
|
||||
2. Wear-слот -> material name.
|
||||
3. Material -> текущая фаза -> `textureName`.
|
||||
4. `Texm` ищется в `Textures.lib` (или lightmap-библиотеке для lightmap-ветки).
|
||||
|
||||
### Ключ анимации (Res8) и mapping (Res19)
|
||||
Fallback:
|
||||
|
||||
```python
|
||||
def decode_anim_key24(buf: bytes, idx: int):
|
||||
o = idx * 24
|
||||
px, py, pz, t = struct.unpack_from('<4f', buf, o)
|
||||
qx, qy, qz, qw = struct.unpack_from('<4h', buf, o + 16)
|
||||
s = 1.0 / 32767.0
|
||||
return (px, py, pz), t, (qx * s, qy * s, qz * s, qw * s)
|
||||
```
|
||||
- материал: `DEFAULT`, затем индекс `0`;
|
||||
- текстура/lightmap: fallback-слот движка.
|
||||
|
||||
### Эффектный поток (FXID)
|
||||
## 7. Что уже закрыто для 1:1
|
||||
|
||||
```python
|
||||
FX_CMD_SIZE = {1:224,2:148,3:200,4:204,5:112,6:4,7:208,8:248,9:208,10:208}
|
||||
1. Бинарный контракт базовых MSH таблиц.
|
||||
2. Контракт animation sampling (`Res8 + Res19`).
|
||||
3. Контракт MAT0/WEAR/Texm на уровне чтения и применения в кадре.
|
||||
4. Формат FXID-контейнера, командный поток и fixed command sizes.
|
||||
5. Валидация на retail-корпусе через `tools/msh_doc_validator.py` (0 ошибок/предупреждений).
|
||||
|
||||
def parse_fx_payload(raw: bytes):
|
||||
cmd_count = struct.unpack_from('<I', raw, 0)[0]
|
||||
ptr = 0x3C
|
||||
cmds = []
|
||||
for _ in range(cmd_count):
|
||||
w = struct.unpack_from('<I', raw, ptr)[0]
|
||||
op = w & 0xFF
|
||||
enabled = (w >> 8) & 1
|
||||
size = FX_CMD_SIZE[op]
|
||||
cmds.append((op, enabled, ptr, size))
|
||||
ptr += size
|
||||
if ptr != len(raw):
|
||||
raise ValueError('tail bytes after command stream')
|
||||
return cmds
|
||||
```
|
||||
## 8. Статус покрытия и что осталось до 100%
|
||||
|
||||
### Texm (header + mips + Page)
|
||||
|
||||
```python
|
||||
def parse_texm(raw: bytes):
|
||||
magic, w, h, mips, f4, f5, unk6, fmt = struct.unpack_from('<8I', raw, 0)
|
||||
assert magic == 0x6D786554 # 'Texm'
|
||||
bpp = 1 if fmt == 0 else (2 if fmt in (565, 556, 4444) else 4)
|
||||
pix_sum = 0
|
||||
mw, mh = w, h
|
||||
for _ in range(mips):
|
||||
pix_sum += mw * mh
|
||||
mw = max(1, mw >> 1)
|
||||
mh = max(1, mh >> 1)
|
||||
off = 32 + (1024 if fmt == 0 else 0) + bpp * pix_sum
|
||||
page = None
|
||||
if off + 8 <= len(raw) and raw[off:off+4] == b'Page':
|
||||
n = struct.unpack_from('<I', raw, off + 4)[0]
|
||||
page = [struct.unpack_from('<4h', raw, off + 8 + i * 8) for i in range(n)]
|
||||
return (w, h, mips, fmt, f4, f5, unk6, page)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Часть 6. Остаточные семантические вопросы
|
||||
|
||||
Пункты ниже **не блокируют 1:1-парсинг/рендер/интерполяцию** (все бинарные структуры уже определены), но их человеко‑читаемая трактовка может быть уточнена дополнительно.
|
||||
|
||||
## 6.1. Batch table — смысл `unk4/unk6/unk14`
|
||||
|
||||
Физическое расположение полей известно, но доменное имя/назначение не зафиксировано:
|
||||
|
||||
- `unk4` (`+0x04`)
|
||||
- `unk6` (`+0x06`)
|
||||
- `unk14` (`+0x0E`)
|
||||
|
||||
## 6.2. Node flags и имена групп
|
||||
|
||||
- Биты в `Res1.hdr0` используются в ряде рантайм‑веток, но их «геймдизайн‑имена» неизвестны.
|
||||
- Для group‑индекса `0..4` не найдено текстовых label'ов в ресурсах; для совместимости нужно сохранять числовой индекс как есть.
|
||||
|
||||
## 6.3. Slot tail `unk30..unk40`
|
||||
|
||||
Хвост слота (`+0x30..+0x43`, `5×uint32`) стабильно присутствует в формате, но движок не делает явной семантической декомпозиции этих пяти слов в path'ах загрузки/рендера/коллизии.
|
||||
|
||||
## 6.4. Effect command payload semantics
|
||||
|
||||
Container/stream формально полностью восстановлен (header, opcode, размеры, инстанцирование). Остаётся необязательная задача: дать «человеко‑читаемые» имена каждому полю внутри payload конкретных opcode.
|
||||
|
||||
## 6.5. Поля `TexmHeader.flags4/flags5/unk6`
|
||||
|
||||
Бинарный layout и декодер известны, но значения этих трёх полей в контенте используются контекстно; для 1:1 достаточно хранить/восстанавливать их без модификации.
|
||||
|
||||
## 6.6. Что пока не хватает для полноценного обратного экспорта (`OBJ -> MSH/NRes`)
|
||||
|
||||
Ниже перечислено то, что нужно закрыть для **lossless round-trip** и 1:1‑поведения при импорте внешней геометрии обратно в формат игры.
|
||||
|
||||
### A) Неполная «авторская» семантика бинарных таблиц
|
||||
|
||||
1. `Res2` header (`первые 0x8C`): не зафиксированы все поля и правила их вычисления при генерации нового файла (а не copy-through из оригинала).
|
||||
2. `Res7` tri-descriptor: для 16‑байтной записи декодирован базовый каркас, но остаётся неформализованной часть служебных бит/полей, нужных для стабильной генерации adjacency/служебной топологии.
|
||||
3. `Res13` поля `unk4/unk6/unk14`: для парсинга достаточно, но для генерации «канонических» значений из голого `OBJ` правила не определены.
|
||||
4. `Res2` slot tail (`unk30..unk40`): семантика не разложена, поэтому при экспорте новых ассетов нет детерминированной формулы заполнения.
|
||||
|
||||
### B) Анимационный path ещё не закрыт как writer
|
||||
|
||||
1. Нужен полный writer для `Res8/Res19`:
|
||||
- точная спецификация байтового формата на запись;
|
||||
- правила генерации mapping (`Res19`) по узлам/кадрам;
|
||||
- жёсткая фиксация округления как в x87 path (включая edge-case на границах кадра).
|
||||
2. Правила биндинга узлов/строк (`Res10`) и `slotFlags` к runtime‑сущностям пока описаны частично и требуют формализации именно для импорта новых данных.
|
||||
|
||||
### C) Материалы, текстуры, эффекты для «полного ассета»
|
||||
|
||||
1. Для `Texm` не завершён writer, покрывающий все используемые режимы (включая palette path, mip-chain, `Page`, и правила заполнения служебных полей).
|
||||
2. Для `FXID` известен контейнер/длины команд, но не завершена field-level семантика payload всех opcode для генерации новых эффектов, эквивалентных оригинальному пайплайну.
|
||||
3. Экспорт только `OBJ` покрывает геометрию; для игрового ассета нужен sidecar-слой (материалы/текстуры/эффекты/анимация), иначе импорт неизбежно неполный.
|
||||
|
||||
### D) Что это означает на практике
|
||||
|
||||
1. `OBJ -> MSH` сейчас реалистичен как **ограниченный static-экспорт** (позиции/индексы/часть batch/slot структуры).
|
||||
2. `OBJ -> полноценный игровой ресурс` (без потерь, с поведением 1:1) пока недостижим без закрытия пунктов A/B/C.
|
||||
3. До закрытия пунктов A/B/C рекомендуется использовать режим:
|
||||
- геометрия экспортируется из `OBJ`;
|
||||
- неизвестные/служебные поля берутся copy-through из референсного оригинального ассета той же структуры.
|
||||
1. Полная field-level семантика части служебных полей:
|
||||
- `Batch20` opaque-поля;
|
||||
- хвостовые служебные поля slot-записей;
|
||||
- часть флагов узлов/групп.
|
||||
2. Полный writer-путь для авторинга новых анимированных ассетов (не только roundtrip существующих).
|
||||
3. Полная формализация семантики FX payload полей по каждому opcode для генерации новых эффектов, а не только для корректного чтения/исполнения.
|
||||
4. Полный канонический writer `Texm` для всех редких форматов и edge-case комбинаций служебных флагов.
|
||||
5. Сквозной «импорт внешнего ассета -> игровой пакет» с формальной спецификацией sidecar-метаданных (материал/эффект/анимация).
|
||||
|
||||
Reference in New Issue
Block a user