203 lines
9.1 KiB
Markdown
203 lines
9.1 KiB
Markdown
# NRes
|
|
|
|
`NRes` — базовый контейнер ресурсов движка Parkan: Iron Strategy.
|
|
Страница фиксирует формат на диске и runtime-контракт чтения/поиска/сохранения в высокоуровневом виде, без привязки к внутренним адресам и именам из дизассемблера.
|
|
|
|
Связанная страница:
|
|
|
|
- [RsLi](rsli.md)
|
|
|
|
## 1. Назначение
|
|
|
|
`NRes` используется как универсальный архив:
|
|
|
|
- 3D-модели (`*.msh`, `*.rlb`);
|
|
- текстуры (`Texm`);
|
|
- материалы (`MAT0`);
|
|
- эффекты (`FXID`);
|
|
- миссионные и служебные ресурсы.
|
|
|
|
Формат поддерживает:
|
|
|
|
- чтение;
|
|
- поиск по имени;
|
|
- редактирование (add/replace/remove);
|
|
- полную пересборку архива.
|
|
|
|
## 2. Общий layout файла
|
|
|
|
```text
|
|
[Header: 16]
|
|
[Data region: variable, 8-byte aligned chunks]
|
|
[Directory: entry_count * 64, всегда в конце файла]
|
|
```
|
|
|
|
Критично: каталог всегда расположен в конце файла.
|
|
|
|
## 3. Заголовок (16 байт)
|
|
|
|
Все значения little-endian.
|
|
|
|
| Offset | Size | Type | Значение |
|
|
|---:|---:|---|---|
|
|
| 0 | 4 | char[4] | `NRes` |
|
|
| 4 | 4 | u32 | `0x00000100` (версия 1.0) |
|
|
| 8 | 4 | i32 | `entry_count` (должен быть `>= 0`) |
|
|
| 12 | 4 | u32 | `total_size` (должен быть равен фактическому размеру файла) |
|
|
|
|
Производные значения:
|
|
|
|
- `directory_size = entry_count * 64`;
|
|
- `directory_offset = total_size - directory_size`.
|
|
|
|
Ограничения:
|
|
|
|
- `directory_offset >= 16`;
|
|
- `directory_offset + directory_size == total_size`.
|
|
|
|
## 4. Запись каталога (64 байта)
|
|
|
|
| Offset | Size | Type | Поле |
|
|
|---:|---:|---|---|
|
|
| 0 | 4 | u32 | `type_id` |
|
|
| 4 | 4 | u32 | `attr1` |
|
|
| 8 | 4 | u32 | `attr2` |
|
|
| 12 | 4 | u32 | `size` (размер payload) |
|
|
| 16 | 4 | u32 | `attr3` |
|
|
| 20 | 36 | char[36] | `name_raw` (C-строка) |
|
|
| 56 | 4 | u32 | `data_offset` |
|
|
| 60 | 4 | u32 | `sort_index` |
|
|
|
|
### 4.1. Имя ресурса (`name_raw`)
|
|
|
|
Контракт:
|
|
|
|
- максимум 35 полезных байт + NUL;
|
|
- допускается ровно один терминатор внутри 36-байтового поля;
|
|
- имя сравнивается регистронезависимо по ASCII-правилу (`A..Z` -> `a..z`).
|
|
|
|
Для writer/editor:
|
|
|
|
- запрещено писать NUL внутри полезной части имени;
|
|
- запрещены имена длиной > 35 байт.
|
|
|
|
### 4.2. Диапазон данных (`data_offset`, `size`)
|
|
|
|
Для каждой записи:
|
|
|
|
- `data_offset >= 16`;
|
|
- `data_offset + size <= directory_offset`.
|
|
|
|
Практически (канонический writer): каждый payload начинается с 8-байтного выравнивания.
|
|
|
|
## 5. Таблица сортировки (`sort_index`)
|
|
|
|
`sort_index` задает перестановку «отсортированный список -> исходный индекс записи».
|
|
|
|
Пусть:
|
|
|
|
- `entries[i]` — i-я запись каталога в исходном порядке;
|
|
- `P` — массив индексов `0..entry_count-1`, отсортированный по `entries[idx].name` (ASCII case-insensitive).
|
|
|
|
Тогда в канонической записи:
|
|
|
|
- `entries[i].sort_index = P[i]`.
|
|
|
|
Это именно таблица для бинарного поиска по имени, а не «ранг текущей записи».
|
|
|
|
## 6. Поиск по имени
|
|
|
|
Алгоритм поиска:
|
|
|
|
1. Выполнить бинарный поиск по диапазону `i in [0, entry_count)`.
|
|
2. На шаге `i` взять `target = entries[i].sort_index`.
|
|
3. Сравнить искомое имя с `entries[target].name` (ASCII case-insensitive).
|
|
4. При совпадении вернуть `target`.
|
|
|
|
Fail-safe поведение:
|
|
|
|
- если `sort_index` некорректен (выход за диапазон), реализация должна перейти на линейный fallback по всем записям;
|
|
- fallback использует то же ASCII case-insensitive сравнение.
|
|
|
|
## 7. Каноническая пересборка архива
|
|
|
|
Канонический writer выполняет:
|
|
|
|
1. Пишет заглушку заголовка (16 байт).
|
|
2. Пишет payload всех записей в текущем порядке.
|
|
3. После каждого payload добавляет 0-padding до кратности 8.
|
|
4. Пересчитывает `sort_index` через сортировку имен.
|
|
5. Дописывает каталог (`entry_count * 64`).
|
|
6. Пересчитывает и записывает `total_size`.
|
|
|
|
Итоговый файл должен удовлетворять всем ограничениям из разделов 3–5.
|
|
|
|
## 8. Режим `raw` (совместимость инструментов)
|
|
|
|
Для служебных инструментов допускается `raw_mode`:
|
|
|
|
- любой бинарный файл трактуется как один «сырой» ресурс;
|
|
- возвращается одна запись (`name = RAW`, `data_offset = 0`, `size = len(file)`).
|
|
|
|
Этот режим не является форматом `NRes` на диске, это только режим открытия.
|
|
|
|
## 9. Контрольные инварианты
|
|
|
|
Минимальный набор проверок при чтении:
|
|
|
|
1. `magic == "NRes"`.
|
|
2. `version == 0x100`.
|
|
3. `entry_count >= 0`.
|
|
4. `header.total_size == file_size`.
|
|
5. Каталог находится в конце файла.
|
|
6. Для каждой записи диапазон данных не пересекает каталог.
|
|
7. Имя корректно C-терминировано и не длиннее 35 байт.
|
|
|
|
Минимальный набор проверок при записи:
|
|
|
|
1. Все имена <= 35 байт и без внутренних NUL.
|
|
2. `sort_index` формирует валидную перестановку `0..N-1`.
|
|
3. Все паддинги между payload состоят из нулевых байт.
|
|
4. `total_size` равен фактической длине выходного файла.
|
|
|
|
## 10. Эмпирическая проверка на retail-корпусе
|
|
|
|
Валидация на полном наборе `testdata/Parkan - Iron Strategy`:
|
|
|
|
- найдено `120` архивов `NRes`;
|
|
- roundtrip `unpack -> repack -> byte-compare`: `120/120` совпали побайтно;
|
|
- критических расхождений формата не обнаружено.
|
|
|
|
Инструмент:
|
|
|
|
- `tools/archive_roundtrip_validator.py`
|
|
|
|
## 11. Статус покрытия и что осталось до 100%
|
|
|
|
Закрыто:
|
|
|
|
- формат заголовка/каталога;
|
|
- правила поиска;
|
|
- каноническая пересборка;
|
|
- строгие инварианты валидатора;
|
|
- побайтовый roundtrip на retail-корпусе.
|
|
|
|
Осталось до полного 100% архитектурного покрытия движка:
|
|
|
|
1. Формальная семантика `attr1/attr2/attr3` для всех типов ресурсов (частично вынесена в профильные страницы `msh`, `material`, `texture`, `fxid`, `terrain`).
|
|
2. Полная спецификация поведения при не-ASCII именах (в реальных игровых архивах используется ASCII-практика; для Unicode-коллации движок не документирован).
|
|
3. Полная спецификация платформенных гарантий атомарной записи (формат данных закрыт, но OS-уровневые гарантии замены файла зависят от платформы и файловой системы).
|
|
## 12. Специализация `objects.rlb`
|
|
|
|
Хотя `objects.rlb` формально является обычным `NRes`, его payload имеет отдельный семантический контракт:
|
|
|
|
- запись каталога соответствует одному объектному прототипу;
|
|
- payload записи - массив фиксированных ссылок `ObjectRef64` (`archive_name[32] + resource_name[32]`);
|
|
- runtime-резолв меша выполняется через эти ссылки, а не через имя entry `*.msh` внутри `objects.rlb`.
|
|
|
|
Это означает, что `objects.rlb` должен рассматриваться не как архив мешей, а как реестр привязок между mission/unit-ключами и фактическими ресурсами.
|
|
|
|
См. детальную страницу:
|
|
|
|
- [Object registry (`objects.rlb`)](object-registry.md)
|