278 lines
14 KiB
Markdown
278 lines
14 KiB
Markdown
# 3D implementation notes
|
||
|
||
Контрольные заметки, сводки алгоритмов и остаточные семантические вопросы по 3D-подсистемам.
|
||
|
||
---
|
||
|
||
## 5.1. Порядок байт
|
||
|
||
Все значения хранятся в **little‑endian** порядке (платформа x86/Win32).
|
||
|
||
## 5.2. Выравнивание
|
||
|
||
- **NRes‑ресурсы:** данные каждого ресурса внутри NRes‑архива выровнены по границе **8 байт** (0‑padding).
|
||
- **Внутренняя структура ресурсов:** таблицы Res1/Res2/Res7/Res13 не имеют межзаписевого выравнивания — записи идут подряд.
|
||
- **Vertex streams:** stride'ы фиксированы (12/4/8 байт) — вершинные данные идут подряд без паддинга.
|
||
|
||
## 5.3. Размеры записей на диске
|
||
|
||
| Ресурс | Запись | Размер (байт) | 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 |
|
||
|
||
## 5.4. Вычисление количества элементов
|
||
|
||
Количество записей вычисляется из размера ресурса:
|
||
|
||
```
|
||
count = resource_data_size / record_stride
|
||
```
|
||
|
||
Например:
|
||
|
||
- `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`
|
||
|
||
Для 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)
|
||
```
|
||
|
||
### Нормали (Res4)
|
||
|
||
```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)),
|
||
)
|
||
```
|
||
|
||
### UV‑координаты (Res5)
|
||
|
||
```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)
|
||
```
|
||
|
||
### Кодирование нормали (для экспортёра)
|
||
|
||
```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 (безопасное значение)
|
||
)
|
||
```
|
||
|
||
### Кодирование UV (для экспортёра)
|
||
|
||
```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))))
|
||
)
|
||
```
|
||
|
||
### Строки узлов (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
|
||
```
|
||
|
||
### Ключ анимации (Res8) и mapping (Res19)
|
||
|
||
```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)
|
||
```
|
||
|
||
### Эффектный поток (FXID)
|
||
|
||
```python
|
||
FX_CMD_SIZE = {1:224,2:148,3:200,4:204,5:112,6:4,7:208,8:248,9:208,10:208}
|
||
|
||
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
|
||
```
|
||
|
||
### 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 из референсного оригинального ассета той же структуры.
|