diff options
Diffstat (limited to 'docs/tomes/01-guide.md')
| -rw-r--r-- | docs/tomes/01-guide.md | 253 |
1 files changed, 25 insertions, 228 deletions
diff --git a/docs/tomes/01-guide.md b/docs/tomes/01-guide.md index cc4e4c0..e83c9b8 100644 --- a/docs/tomes/01-guide.md +++ b/docs/tomes/01-guide.md @@ -1,115 +1,19 @@ -# I. Путеводитель и методика - -Первый том задаёт язык и правила всей документации. Он объясняет, как читать -технические главы, какие термины используются для игрового runtime, как -разделяются уровни уверенности и какие требования предъявляются к реализации, -которая должна работать с оригинальными данными без потери информации. - -Документация рассчитана на разработчика, который уже умеет читать C/C++, -байтовые форматы, PE-модули и графические pipeline, но не обязательно знаком с -Iron3D. Поэтому этот том не описывает один конкретный crate, package или -физическое деление будущего кода. Он фиксирует контракты: что должно быть -прочитано, сохранено, рассчитано и показано. - -## Назначение книги - -Книга ведёт от общей архитектуры Iron3D к точным форматам данных и алгоритмам -исполнения. Практическая цель -- реализация, способная открыть оригинальный -каталог *Parkan: Iron Strategy*, загрузить миссию, создать мир, провести -игровой шаг и сформировать кадр. - -Форматы в главах описываются как байтовые контракты. Если указано поле -`+0x10`, это означает расположение в потоке или структуре данных, а не -разрешение читать файл прямым `reinterpret_cast`. Для постоянных layouts -используются offsets, проверки размеров, bounded cursor и явное сохранение -неизвестных байтов. Для versioned и variable-length записей приоритет имеет -последовательный parser с контролем границ. - -Игровое поведение описывается не только размером структур. Совместимая -реализация должна учитывать порядок событий, время, fallback-правила, -идентификаторы объектов, численные ограничения, состояние материалов, -границы кадра и правила завершения операций. - -## Маршруты чтения - -**Читатель, новый для игровой разработки**, начинает с базовых понятий этого -тома, затем переходит к архитектуре, игровому циклу и вводу в рендер. После -этого имеет смысл читать главы о миссиях, мире и ресурсных форматах. - -**Разработчик совместимого движка** читает тома II-VII линейно. Технические -главы имеют одинаковую логику: назначение подсистемы, данные на диске, -представление в памяти, алгоритм работы, проверки и требования к новой -реализации. - -**Аналитик оригинальной программы** использует этот том вместе с разделами о -доказательной базе, ABI, результатах корпусных проверок и границах знания. -Факты, согласованные выводы и открытые вопросы должны оставаться разделёнными: -это позволяет расширять реализацию без подмены проверенных контрактов -удобными догадками. - -## Состав документации - -1. **Путеводитель и методика** -- язык предметной области, правила чтения и - процедура проверки. -2. [**Запуск, архитектура и игровой цикл**](02-architecture.md) -- от - `iron_3d.exe` до расчёта и вывода кадра. -3. [**Ресурсная система и форматы**](03-resources.md) -- архивы, кэши, реестры - и служебные данные. -4. [**Мир, миссии и игровой runtime**](04-world.md) -- TMA, ландшафт, ареалы и - создание объектов. -5. [**Геометрия, материалы и рендер**](05-render.md) -- от вершины модели до - изображения на экране. -6. [**Поведение, управление, звук и сеть**](06-behavior.md) -- интерактивные - подсистемы. -7. [**Руководство по полной реализации**](07-implementation.md) -- предлагаемая - архитектура и порядок работ. -8. [**Справочник и доказательная база**](08-evidence.md) -- ABI, - конфигурация, статистика и открытые вопросы. - -Дополнительные краткие определения собраны в -[глоссарии](../appendices/glossary.md). Технические области, где контракт ещё -не закрыт полностью, перечислены в -[границах знания](../appendices/knowledge-boundaries.md). - -## Условные обозначения - -`+0x10` означает смещение поля относительно начала структуры или записи. -`RVA 0x13B60` -- адрес относительно базы PE-модуля. `u16`, `u32`, `i16` и -`float32` обозначают типы фиксированной ширины. `LE` означает little-endian. -`payload` -- полезные данные записи после метаданных контейнера. `EOF` -- точное -завершение файла или ограниченного блока. - -Если в тексте указан hash, RVA или ordinal, значение относится к явно -обозначенному binary profile. Адреса разных сборок не объединяются по имени -функции. При публикации функции нужны минимум модуль, SHA-256 сборки и RVA. - -Размеры структур выражаются в байтах. Счётчики и offsets считаются частью -формата, даже когда их можно восстановить из длины файла. Padding, reserved -поля, неизвестные хвосты и gaps не нормализуются без доказанного правила. - -## Совместимость - -Слово "совместимость" в этой книге имеет несколько уровней. - -**Reader** умеет открыть файл, проверить границы, извлечь известные поля и -сохранить неизвестные bytes так, чтобы данные можно было записать обратно. - -**Viewer** умеет показать ресурс: модель, texture, material, эффект или карту. -Viewer может быть полезен для анализа, но он не доказывает поведение runtime. - -**Runtime** умеет создать мир, зарегистрировать объекты, исполнять события, -обновлять время, применять контроллеры, выбирать видимое состояние и передавать -его рендеру. - -**Полноценный движок** дополнительно воспроизводит порядок операций, численные -правила, fallback-поведение, resource lifetime, reference ownership, pause, -manual input, сетевые идентификаторы, boundaries кадра и состояние -интерактивных подсистем. - -Поэтому файл может быть "прочитан правильно", но всё ещё не быть реализованным -на уровне движка. Например, reader MSH может восстановить вершины и индексы, -viewer может нарисовать mesh, а runtime обязан ещё сохранить material slots, -animation state, bounds, LOD, visibility, collision и связи с объектом мира. +# I. Путеводитель + +Игра выглядит как непрерывное движение, но компьютер строит её из отдельных +шагов. Он читает ввод, обновляет мир, вычисляет положение моделей и рисует +очередной кадр. Чтобы воспроизвести старую игру, нужно понять как её файлы, +так и правила этих шагов. + +Книга не требует опыта игровой разработки. Ниже объясняются основные понятия, +а последующие главы показывают их на конкретных данных «Паркана». +Подробные таблицы адресов и байтов полезны при реализации; при первом чтении +их можно пропустить. + +`+0x10` означает смещение в байтах от начала записи. `RVA` — адрес относительно +начала загруженной DLL. `u16`, `u32`, `i16`, `float32` — числа фиксированного +размера. `LE` означает little-endian: младший байт числа записан первым. +`EOF` — конец файла. Неизвестные поля сохраняются без изменений. ## Движок как программа длительного действия @@ -250,122 +154,15 @@ Writer пересчитывает только производные значе записей, сортировочные таблицы и padding, если правило доказано. Unknown fields и reserved ranges сохраняются побайтно. -## Иерархия доказательств - -Документация использует четыре уровня уверенности. - -**Прямое наблюдение** -- поле, значение или последовательность видны в -инструкции программы, таблице PE, экспорте, строке, обработчике файла или в -самом ресурсе. Это самый сильный уровень. - -**Корпусное подтверждение** -- правило проверено на всех подходящих файлах -одного или нескольких явно названных наборов: демоверсии, Части 1 и Части 2. -Например, базовый корпус содержит 435 моделей MSH, 518 textures Texm и 923 -эффекта FXID, прошедших структурные проверки без ошибок; полные части расширяют -эту матрицу вариантов. - -**Согласованный вывод** -- назначение восстановлено по нескольким независимым -признакам: вызывающим функциям, vtable slots, строкам ошибок, диапазонам -значений и связям между форматами. Такой вывод пригоден для реализации, но его -численные детали следует проверять тестами. - -**Открытый вопрос** -- данные можно читать и сохранять, однако предметный смысл -поля или редкой ветки не доказан. Такие bytes нельзя обнулять, -переупорядочивать или превращать в authoring API. - -Уровень уверенности должен быть виден из формулировки. "Поле равно" означает -проверенный layout или значение. "Вероятно отвечает за" означает согласованный -вывод. "Неизвестно" означает сохранять без изменения и не строить вокруг этого -публичный контракт. - -## Проверенные материалы - -Локальный набор проверки включает демоверсию, полные каталоги Частей 1 и 2, -исполняемые файлы, 15 DLL каждой сборки и игровые ресурсы. DLL из -первоначального архива и DLL демоверсии совпали по SHA-256: `15/15`, поэтому -выводы по этому коду и demo-ресурсам образуют один доказательный профиль. - -Исполняемый файл демоверсии `iron_3d.exe` имеет размер 36 864 байта, PE32/x86, -entry RVA `0x141E`, image base `0x400000` и SHA-256 -`b0a8b0db1c3a8698c4d4604d89c655496bd91ac1f8859a455e8a45838aebfbd6`. - -Исполняемые файлы Частей 1 и 2 также имеют размер 36 864 байта и побайтно -совпадают между собой, но относятся к другому binary profile: entry RVA -`0x147E`, SHA-256 -`f476af85c034a4b4f34f49d0806e4dff397b5da0ee26d382a7674231144979f7`. - -Полные каталоги Частей 1 и 2 суммарно включают 60 TMA, 1 101 unit DAT, 254 -NRes-файла и 14 975 NRes entries. Все контейнеры и TMA прошли bounded parser до -точного EOF; полный достижимый граф обеих частей разрешился без ошибок. - -## Процедура проверки - -Проверка строится как воспроизводимая цепочка: - -1. Снять PE-метаданные, хэши, импорты, экспорты, ordinals, RTTI и строки. -2. Построить граф вызовов между модулями и отметить фабрики подсистем. -3. Разобрать функции запуска, загрузчики файлов, главный цикл и критические - vtable-вызовы. -4. Проверить форматы независимыми reader-скриптами с контролем границ и точного - завершения файла. -5. Построить цепочку миссия -> объект -> прототип -> модель -> материал -> - texture. -6. Сравнить счётчики, диапазоны, ссылки и размеры на всём доступном корпусе. - -Ключевой результат сквозной проверки демо-миссий: все 201 объектов шести -миссий разрешились в 501 запрос прототипов, затем в 501 модель, 501 таблицу -WEAR, 3 879 слотов материалов и 5 085 ссылок на textures или lightmaps. Ошибок -в фактически исполняемом пути нет. - -## Что не считается доказательством - -Удобное имя поля не доказывает его назначение. Совпадение layout с текущей -реализацией не доказывает поведение оригинального runtime. Успешный viewer не -доказывает writer. Успешный reader одного файла не доказывает формат всего -корпуса. Совпадение ABI не доказывает побайтную идентичность всех сборок. - -Если локальные данные и предположение расходятся, приоритет имеют исполняемый -код, реальные ресурсы и взаимные invariants между форматами. Неизвестное поле -лучше оставить без имени, чем дать ему ложное предметное значение. - -## Требования к воспроизводимости - -Каждая новая реализация должна иметь strict parser mode, lossless roundtrip -mode и набор corpus tests. Неизвестные поля сохраняются побайтно. Любое -присвоенное полю имя должно сопровождаться наблюдаемым поведением или тестом. -Численные правила -- округление, порядок умножения, RNG и время -- считаются -частью формата исполнения, даже если файл читается правильно. - -Минимальный отчёт проверки должен фиксировать: - -1. build profile и hashes модулей; -2. путь или ключ ресурса; -3. размер входного файла и hash входных bytes; -4. версию parser-а или commit реализации; -5. список включённых quirks; -6. число прочитанных записей и точку EOF; -7. ошибки, предупреждения и unknown ranges; -8. результат roundtrip, если writer участвует в проверке. - -Для runtime-проверок дополнительно нужны mission key, configuration, device -profile, начальное состояние, input/time script и trace значимых callbacks. - -## Разделение профилей -Binary profile описывает исполняемый код: PE-метаданные, exports/imports, -ordinals, hashes, RVA и layout функций. Corpus profile описывает набор файлов: -каталог, миссии, ресурсы, размеры, counts, variants и статистику parser-а. - -Эти профили нельзя смешивать без явной пометки. Один и тот же формат может -иметь общий смысл в разных сборках, но отличаться редкими ветками, адресами -функций или набором встреченных вариантов. Один и тот же address может иметь -смысл только внутри конкретного module hash. - -При расширении документации новое утверждение должно отвечать на три вопроса: +## Проверка предположений -1. Где это видно напрямую? -2. На каком корпусе это проверено? -3. Что должна сделать реализация, если правило нарушено? +Формат подтверждается тем, как оригинальная программа читает запись, и тем, +какие значения встречаются в игровых ресурсах. Изображение из стороннего +просмотрщика помогает заметить ошибку, но само по себе не доказывает формулу. +Для восстановленного поведения оставляем небольшой тест с конкретным входом +и ожидаемым результатом. Для неопределённого поля прямо пишем, что его смысл +неизвестен. -Если на один из вопросов нет ответа, утверждение остаётся согласованным выводом -или открытым вопросом, а не закрытым контрактом. +RVA зависит от сборки DLL. Сравнивая инструкции, сначала сверяют соответствующий +файл с [таблицей оригинальных модулей](../reference/original-binaries.md). |