valentineus/fparkan

Fork 0

Files

T

Valentin Popov 78fc5f1deb

Docs Deploy / Build and Deploy MkDocs (push) Successful in 34s

Details

Test / Lint (push) Failing after 1m7s

Details

Test / Test (push) Has been skipped

Details

Test / Render parity (push) Has been skipped

Details

docs: rewrite MkDocs documentation

2026-06-22 01:58:51 +04:00

57 KiB

Raw Blame History

VIII. Справочник и доказательная база

Восьмой том фиксирует, на чём держится книга: ABI, exports/imports, файловая поверхность, статистика корпусов, открытые вопросы, критерии доказанности и словарь терминов. Это самостоятельная справочная глава: она не заменяет профильные статьи о форматах, но задаёт общий контракт, по которому проверяются реализация, parser-ы, compatibility layer и будущие динамические эксперименты.

Как читать доказательства

Доказательством считается наблюдение, которое можно повторить на конкретном файле, сборке или трассе. Вывод может объединять несколько наблюдений, но он должен сохранять происхождение данных: демоверсия, полная Часть 1 и полная Часть 2 не смешиваются в один безымянный corpus.

Для каждого утверждения полезно различать четыре уровня:

layout-confirmed: известны offset, size, count, bounds и правила безопасного чтения;
corpus-verified: branch или вариант реально встречается в доступных игровых данных;
code-confirmed: branch виден в бинарном коде, но отсутствует в доступном corpus;
behavior-confirmed: поведение подтверждено исполнением оригинальной программы, трассой API/vtable или controlled differential test.

Если поле не имеет доказанного предметного смысла, документация хранит его как opaque field. Это не мешает lossless read/write, но запрещает строить writer, который очищает, переименовывает или пересчитывает такое поле на основании правдоподобной догадки.

ABI и границы модулей

Базовый binary profile

Все исследованные модули -- 32-битные PE для x86, собранные C++-компилятором эпохи MSVC6. Публичная граница сочетает именованные exports, фабрики C++- объектов, singleton getters и дальнейшие вызовы через vtable.

Для binary shim необходимо учитывать:

__cdecl и __stdcall у свободных функций;
__thiscall у методов, где this передаётся в ECX;
очистку stack, видимую по ret N;
точный порядок virtual slots;
multiple-interface pointer adjustments;
4-byte alignment и native little-endian types;
отсутствие безопасного ABI для STL-контейнеров между современным и старым compiler-ом.

Внутренний новый движок не обязан использовать этот ABI. Он нужен только compatibility layer, который принимает старые DLL-facing interfaces, старый порядок slots и старые ownership rules.

Публичная поверхность DLL

В 15 DLL обнаружено 313 exports:

AniMesh.dll     2    ArealMap.dll    9
Behavior.dll    3    Control.dll     5
Effect.dll      2    Joystick.dll    6
MisLoad.dll     2    Net.dll        37
Ngi32.dll     145    Terrain.dll    13
Wizard.dll      1    World3D.dll    72
ai.dll          2    iron3d.dll      8
services.dll    6

Демоверсия содержит 1 126 imported function slots, а полные Части 1 и 2 -- 1 134. Они включают Win32 runtime, DirectX и межмодульные связи. Большое число exports Ngi32.dll состоит из активного объектного API, математических/resource functions и legacy compatibility stubs.

Compatibility headers должны фиксировать symbol, ordinal, decorated или undecorated name и signature конкретной сборки. Смысловое имя недостаточно: порядок exports и calling convention входят в бинарный контракт.

Композиционный и сервисный слой

iron3d.dll экспортирует восемь функций:

createShell        deleteShell
createGame         deleteGame
createSubsystems   deleteSubsystems
getIGame           getIShell

services.dll публикует шесть getters:

getDisplay
getGUIServer
getNetManager
getResManager
getSoundServer
getTimer

Эти getters возвращают shared interfaces. Caller не должен конструировать concrete implementation или уничтожать singleton напрямую. Для совместимости важны не только адреса функций, но и порядок startup/shutdown, owner/refcount transitions и реакция на failure paths: отсутствие sound device, ошибка display, прерванная загрузка миссии и normal shutdown.

Предметные фабрики

AniMesh:   LoadAgent, LoadAniMesh
ArealMap:  CreateArealMap, CreateSystemArealMap, GetSystemArealMap,
           CreateHallWay, CreateObjectFromScheme, CreateObjectsForDebug,
           CalcFullResearchCost, Debug_TestSchemeType, ShowDebugVector
Behavior:  CreateBehaviour, CreateDistributor, PressDebugKey
Control:   InitializeSettings, LoadControlSystem, LoadPhysicalModel,
           CreateCollManager, CreateCollObject
Effect:    InitializeSettings, CreateFxManager
MisLoad:   CreateMissionData, LoadResearch
AI:        CreateSuperAI, GetSuperAI
Wizard:    CreateWizard
Terrain:   CreateAtmosphere, CreateLightManager, CreatePrimitives,
           CreatePrimitives2, CreateShader, GetShade, GetWorld,
           LoadCamera, stdGetCurrentCamera2, stdSetCurrentCamera2

Фабрика возвращает interface pointer. Конкретный размер объекта и layout остаются внутренними; внешнему коду важны vtable, QueryInterface-подобная negotiation, lifetime methods и правила владения.

World3D export families

72 exports World3D.dll группируются по назначению:

lifecycle: stdInitGame, stdCloseGame, stdCalculateGame, stdRenderGame
objects: CreateObject, AddObjectToGame, AddNewObjectToGame,
         CreateMirrorObject, AddMirrorObjectToGame, AddNewMirrorToGame,
         DeleteGameObject, KillGameObject, CreateQueue, GetQueue
camera:  LoadCamera, stdSetCurrentCamera, stdGetCurrentCamera
input:   UpdateManualEventsList, ClearManualEventsList, stdClearKeyboard,
         converters, scan/string functions, key lock/query, mouse shift
clock:   SetGameTime, PauseGameTime, ResumeGameTime, GetGameTime family
network: netCreateNetWatcher, GetNetPlayerNum and mirror/player helpers
resources/render: material, texture, lightmap and end-of-render helpers
settings/state: CreateGameSettings, SetGameRender, SetStateForGameObjects

World3D является главным местом, где внешний ABI превращается в game loop: input обновляет manual events, calculation проходит queue/world traversal, deferred deletion откладывает фактическое уничтожение объектов, render читает подготовленный snapshot, а end-of-render helpers закрывают временные ресурсы.

Net и Joystick

Net.dll экспортирует создание instance/interface и 33 операции transport lifecycle: provider/session enumeration, setup, create/join/close, player operations, send/receive, latency, addresses, queue size, lobby и netZipData/netUnZipData.

Joystick.dll имеет компактную границу:

QueryJoy
CreateJoy
ReleaseJoy
SetJoyRange
PeekJoyMessage
GetJoyCaps

Эти модули легче всего заменить adapter-ами, потому что их публичная поверхность достаточно узкая. Для native interoperability сохраняются исходные signatures; modern runtime может использовать внутренние typed interfaces.

Ngi32 export families

145 exports Ngi32.dll включают:

resource archives: niOpenResFile, niOpenResFileEx, niOpenResInMem,
                   niCreateResFile, rsOpenLib, rsFind, rsLoad
renderer:          niGetD3DDriverAmount, niSelectD3DDriver,
                   niGetD3DDriverCaps, niGetD3DVideoModeList,
                   niCreate3DRender, niGet3DRender, niGetMaxTextureSize
audio:             niCreate3DSound, niGet3DSound, niGet3DSoundCaps,
                   niMuteSound, rsLoadWave
platform:          allocation, clocks, fixed-memory helpers
math/geometry:     plane, ray, polygon and volume intersection routines
CPU dispatch:      g_FastProc, niGetProcAddress and feature detection
legacy ABI:        n3d*, vrt*, bsp* compatibility entries

Экспорт переменной g_FastProc требует особого shim: consumer получает адрес таблицы, а не результат функции.

Подтверждённые RVA

Адреса указаны как RVA конкретной исследованной сборки:

World3D stdCalculateGame    0x13910
World3D stdRenderGame       0x13B60
World3D sendEndOfRender     0x13D20
World3D UpdateManualEvents  0x10E10
World3D ClearManualEvents   0x11180
World3D DeleteGameObject    0x087B0
Ngi32 g_FastProc            0x3A058

iron3d.dll вызывает calculation около RVA 0x5FA94, 0x604C1, 0x6086B, render около 0x60B2F, а manual-event update находится в Win32 message path около 0xA3759.

RVA используются только для сопоставления и трассировки этой версии. Runtime implementation не должна встраивать их как постоянные игровые идентификаторы. Таблица внутренних RVA хранится по SHA-256 конкретного модуля.

Подтверждённые hashes неизменённых DLL:

World3D.dll 17e4a3089b2583a8cf2356c9db0390b1aba138356a09130d79b4e7e4791da61e
Ngi32.dll   bab9840d94f4e4e74ffc26677724fa896cf4823845504d09a9e025f80016edf5

Vtable и interface negotiation

Вызовы вида object->vfunc(offset) доказывают порядок slots, даже когда имя метода неизвестно. Renderer slots около +0x28, +0x30, +0x34 окружают world traversal; camera и viewport получаются через selector-based interface calls; shared objects используют ранний slot как AddRef-подобную операцию.

Правила реконструкции:

Зафиксировать byte offset slot и число аргументов.
Найти все call sites и типы передаваемых значений.
Отделить доказанное поведение от назначенного имени.
Построить C-compatible shim vtable с точным порядком.
Внутри adapter-а перевести вызов в современный typed interface.

Нельзя добавлять virtual destructor в начало reconstructed interface: это сдвинет все slots.

ABI-матрица Частей 1 и 2

Во всех пятнадцати DLL совпадают export names, ordinals и import sets. Общее число exports остаётся 313. Обе полные части содержат 1 134 imported function slots; значение 1 126 относится к демоверсии и хранится отдельно.

Побайтно идентичны девять DLL:

ai.dll
Behavior.dll
Joystick.dll
MisLoad.dll
Net.dll
Ngi32.dll
Terrain.dll
Wizard.dll
World3D.dll

Пересобраны AniMesh.dll, ArealMap.dll, Control.dll, Effect.dll, iron3d.dll, services.dll.

Изменение export RVA:

AniMesh    2 / 2
Control    5 / 5
iron3d     8 / 8
services   6 / 6
ArealMap   0 / 9
Effect     0 / 2

Нулевое изменение export RVA не доказывает идентичность тела функции: ArealMap.dll и Effect.dll имеют изменённый .text при прежних адресах exports. Compatibility headers фиксируют внешний ABI один раз, но внутренняя таблица адресов, тестов и semantic deltas выбирается по build fingerprint.

Файловая поверхность

Каталог как внешний API

Оригинальная установка -- не просто набор assets. Имена файлов, относительные пути, регистр, конфигурационные ключи и разделение библиотек образуют внешний контракт. Совместимый движок должен принимать каталог без переименования и предварительной распаковки.

Основные root-файлы включают executable и 15 DLL, Iron_3D.ini, Comp.ini, Behavior.ini, ArealMap.ini, BuildDat.lst, input/preload descriptions и набор .rlb/.lib архивов:

objects.rlb
system.rlb
static.rlb
effects.rlb
Material.lib
Textures.lib
LightMap.lib
Palettes.lib
sounds.lib
voices.lib

Parser конфигураций должен сохранять неизвестные keys и секции, поддерживать quoted strings, хранить provenance значения и отличать absent key от explicit default.

`Iron_3D.ini`

Демоверсия содержит секции [CS], [MULTIPLAYER], [TEMP] и [LEVEL_RATIO].

DISPLAY_WIDTH=640          DISPLAY_HEIGHT=480
BITDEPTH=16                CURRENT_D3DCARD=0
WINDOW_MODE=0              FORCE_SOFTWARE_CURSOR=1
RENDER_QUALITY=2           REFLECTIONS=0
EMBOSS_BUMP=0              EMBM=0
PLAY_CD_MUSIC=1            MOUSE_SENS=100
JOY_SENS=100               MOUSE_REV_Y=0
JOY_REV_Y=0                JOY_ENABLE=0
SUBTITLES=1

FORCE_CD_SOUND хранит строку пути. Multiplayer задаёт default IP, login и password. [TEMP] содержит normalization и offence/defence ranges, [LEVEL_RATIO] -- коэффициенты сложности 0.5, 0.7, 1.0.

Parser не должен считать имена регистрозависимыми без отдельного доказательства. Effective value, raw value и факт присутствия ключа хранятся раздельно.

`Comp.ini`: реестр компонентов

Формат строки:

<CID> <DLL-name> <Function-name> [comment]

Подтверждённая таблица:

0 terrain.dll LoadLandscape
1 terrain.dll LoadBuilding
2 terrain.dll LoadCamera
3 animesh.dll LoadAgent
4 animesh.dll LoadAgent
5 terrain.dll CreateAtmosphere
6 terrain.dll CreateShader
7 misload.dll LoadResearch

World3D использует этот файл как динамический component registry. Standalone runtime может сопоставить CID внутренним фабрикам, но compatibility loader должен поддерживать исходные DLL/function strings и комментарии //.

`Behavior.ini` и `ArealMap.ini`

Demo Behavior.ini задаёт logging, debug rendering и controller switches:

LogFile=Behavior.log       SaveLog=0
MaxErrorLevel=1            DefErrorLevel=2
LookBugMode=0              ShowVectors=0
NoZBuffer=0                LockBehaviour=0
UseDebugKey=1              GiveDefaultOrder=0
DefaultOrderPhase=10       DeterminMode=0
ImmortalHero=0             UseWizard=1

Код Behavior также ищет дополнительные PathFind_* и network parameters. В demo-файле они отсутствуют, следовательно используются compiled defaults или другой источник; нельзя приписывать им произвольные значения.

ArealMap.ini содержит log switches, ShowAreals, Areal_NoZBuffer, HallWay_NoZBuffer, EdgeUp и RunBehDebug.

Миссии, UI и сохранения

Типичный каталог миссии содержит:

data.tma
mission.cfg
briefing.cfg
messages.cfg

mission.cfg -- текстовое описание именованных resource objects. Блок начинается object <name>, содержит desc, library, libtype, числовой type и произвольные именованные параметры, затем end. В демоверсии через него определяются ambient music loops/variations и другие mission services.

briefing.cfg и messages.cfg относятся к пользовательскому представлению и текстовым событиям. Binary TMA остаётся источником placement и properties; эти файлы дополняют, а не заменяют его.

Отдельные поверхности:

MISSIONS/SCRIPTS/*.scr, *.fml, *.trf, varset.var
MISSIONS/dispatcher.ini
ui/shell_ctrls.cfg
ui/menu_resources.cfg
ui/cursor.cfg
ui/game_resources.cfg
ui/hq.cfg
DATA/TextRes.cfg
SAVE/saveslots.cfg

Dispatcher демоверсии содержит секцию [COMPLETE]; полные части расширяют campaign state и набор миссионных файлов. UI-config следует читать отдельным generic object/config parser-ом, сохраняя порядок блоков и неизвестные fields. TextRes.cfg связывает ключи с локализованными строками.

Save slot list не является полным savegame state. Для полной совместимости нужно отдельно восстановить binary save payload, campaign dispatcher и serialization world/script/AI/RNG.

Правила файловой совместимости

Поддерживать / и \ во входных legacy paths.
Разрешать paths относительно root игры и mission context.
Сохранять исходное написание для log и roundtrip.
Использовать ASCII case-insensitive lookup внутри архивов.
Учитывать CP1251/ANSI строки там, где встречается локализованный текст.
Не применять Unicode normalization к фиксированным resource names.
Различать физически отсутствующий файл и отсутствующий entry в существующем архиве.
Не требовать одинакового регистра имени файла на case-sensitive системах: resolver строит индекс каталога.

Все найденные конфигурации должны иметь schema с defaults, provenance и признаком present. Это позволяет отличить исходный default от явно заданного пользователем значения.

Различия файловой поверхности Частей 1 и 2

Часть 2 добавляет ui_factory.lib -- NRes с шестью Texm entries. ui/minimap.lib увеличен примерно с 6,95 до 10,10 МБ. gamefont.rlb и sprites.lib побайтно совпадают между частями.

Iron_3D.ini Части 2 добавляет ключи SFX_VOLUME, CD_VOLUME, DEBUG_KEYS_ON, меняет некоторые defaults (MOUSE_SENS, MAP_ALPHA128) и локализует строки login/password. Это подтверждает правило schema + provenance: parser хранит не только effective value, но и признак присутствия ключа в конкретной сборке.

BuildDat.lst Части 2 использует более полные пути под UNITS\BUILDS\AI\...; category masks при этом остаются логическим контрактом, а physical path -- частью content profile.

TextRes.cfg и TextRes.dll значительно расширены. Localized text, resource identifier и path normalization должны оставаться разными слоями: локализация текста не меняет ASCII-casefold policy имён entries.

Результаты проверки корпусов

Demo baseline

Демоверсия содержит iron_3d.exe, те же 15 DLL и сокращённый набор миссий/ресурсов. Все 15 DLL совпали с первоначально исследованными файлами по SHA-256. Поэтому executable, бинарный код DLL и demo-assets относятся к одной совместимой технологической сборке.

modules: 16, из них DLL: 15
DLL exports: 313
DLL imports: 1126
DLL identity: 15/15

iron_3d.exe: 36 864 байта, PE32/x86, image base 0x400000, entry RVA 0x141E, timestamp 28 июня 2001 года, SHA-256 b0a8b0db1c3a8698c4d4604d89c655496bd91ac1f8859a455e8a45838aebfbd6.

Миссии и сквозные ссылки

Шесть TMA разобраны до точного EOF: суммарно 20 paths, 15 clans, 201 placed objects и 1 extra record. 48 объектов ссылаются на unit DAT, 153 -- на прямые prototype keys. Unit-файлы раскрыли 348 компонентов.

Сквозной результат:

501 prototype requests   501 resolved
501 MSH requests         501 resolved
501 WEAR requests        501 resolved
3879 material slots      3879 resolved
5067 texture requests    5067 resolved
18 lightmap requests     18 resolved
failures                 0

Это самое сильное интеграционное подтверждение текущего корпуса: имена, архивы, ASCII casefold и fallback согласуются между реальными форматами.

Реестр и unit DAT

objects.rlb содержит 590 prototype entries:

554 имеют прямую MSH-ссылку
549 прямых MSH разрешаются в demo-каталоге
34 раскрываются через родительский prototype и локальный BASE
7 не дают доступной геометрии
41 ссылка общего реестра указывает на отсутствующий demo-content

Негеометрические или неразрешённые глобальные entries:

sun_01
sun_02
ws_al_01
ws_al_02
ws_fl_01
ws_hm_01
ws_hm_02

Они не входят в фактически требуемую цепочку проверенных миссий.

Проверено 425 unit DAT, 5 219 records, errors 0. Все records имеют kind 1 и archive objects.rlb; в 5 205 name fields есть ненулевые хвостовые байты после string terminator. Такой tail является данными, а не мусором, если цель -- lossless roundtrip.

Модели

Проверено 435 MSH без errors/warnings; 157 анимированных. Диапазоны: 1-38 nodes, 1-112 slots, 12-9 686 vertices, 1-439 batches.

414 моделей: types [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]

Type 17 непуст у 29 моделей; type 20 встречается у 21. Редкий variant type 1 найден в system.rlb::MTCHECK.MSH.

Повторная проверка terrain исправила layout face: vertex indices находятся с +0x08, neighbor indices с +0x0E. Эта локальная проверка имеет приоритет над ранними черновыми описаниями.

Материалы и текстуры

Проверено 457 WEAR, 905 MAT0 и 518 Texm без ошибок. У всех MAT0 attr2 = 6. 531 материал содержит одну phase; максимальное число phases -- 29. У 860 материалов один animation block, у 43 -- два, у 2 -- восемь.

Распределение Texm по форматам:

indexed 15
565     155
4444    59
888     52
8888    237

Форматы 556 и 88 присутствуют в loader-е, но не встречаются в demo-assets. 65 текстур содержат Page; размеры лежат от 8x8 до 256x256. Все 385 уникальных texture references из MAT0 разрешаются.

Эффекты

Проверено 923 FXID без ошибок. Наиболее часты команды 3, 7, 1 и 2. Команда 6 в данных демоверсии не встречается. Наблюдаются режимы времени 0, 1, 2, 4, 5, 14, 15, 16 и 17.

Карты

Шесть Land.msh и шесть Land.map проходят проверку без ошибок. Всего 3 811 ареалов; grid всегда 128x128, максимальное число candidates в ячейке -- 10, poly_count во всех записях равен нулю.

AutoMAP  3051 vertices, 3174 faces, 343 areas
PROL    11125 vertices, 9234 faces, 731 area
Tut_1    8827 vertices, 8290 faces, 378 areas
Tut_2    9456 vertices, 8996 faces, 900 areas
Tut_3    9833 vertices, 8560 faces, 722 areas
Tut_4    9022 vertices, 8612 faces, 737 areas

Максимальное отклонение длины areal normal от единицы около 1.05e-7.

Вспомогательные форматы

CTPT   284 resources, 3599 points, errors 0
NDPR   494 resources, 1915 records, errors 0
BASE    30 resources, errors 0
EXPL   144 resources, versions 1/2/3, errors 0
reference arrays 585 resources, 2956 records, errors 0
SUND     2 resources, 12 keys, errors 0
CTLD   531 payloads, errors 0
TRF      5 files, errors 0
preload 38 entries
ANI      8 resources
SKE      6 resources

CTPT names подтверждают attachment semantics: TurretCenter, TurretDirect, CameraCenter, TargetDirect, Root, Sfx, Width, Height, Dir и другие.

Как читать статистику

Нулевое число parser errors подтверждает layout и диапазонные инварианты на имеющихся variants, но не автоматически раскрывает предметный смысл каждого opaque field. Отсутствие opcode или poly branch в corpus означает, что эту ветку нельзя считать corpus-verified.

Особенно важно различать весь архив и достижимый runtime path. В objects.rlb есть ссылки на вырезанный demo-content, однако шесть миссий не требуют их. Поэтому quality gate имеет два отчёта: global archive health и mission reachability.

Полные каталоги Частей 1 и 2

Статистика демоверсии остаётся неизменной. Полные Части 1 и 2 образуют два самостоятельных профиля с отдельными manifests, hashes и golden data.

Часть 1:

files 1 017, bytes 197 056 957
NRes 120 / 6 804 entries
TMA 29 / 864 objects / 28 extras
unit DAT 425 / 5 219 records
objects.rlb 590 prototypes
MSH 435, MAT0 905, Texm 518, FXID 923
Land maps 33 / 34 662 areals
reachable prototypes 4 701
materials 36 954, textures 48 806, lightmaps 139
reachability failures 0

Часть 2:

files 1 302, bytes 358 004 931
NRes 134 / 8 171 entries
TMA 31 / 885 objects / 41 extras
unit DAT 676 / 8 145 records
objects.rlb 683 prototypes
MSH 511, MAT0 1 127, Texm 631, FXID 1 065
Land maps 32 / 18 984 areals
reachable prototypes 5 845
materials 50 888, textures 68 603, lightmaps 214
reachability failures 0

Bootstrap Частей 1 и 2 идентичен. Девять DLL идентичны, шесть пересобраны при сохранённом ABI. Активные NRes entries сравниваются так: 3 733 идентичны, 2 503 имеют изменённый payload, 1 934 добавлены в Части 2, 567 удалены. Это показывает стабильность форматов при существенной переработке content, особенно MSH, CTLD и FXID.

Границы знания

Закрытые или практически закрытые области

Startup bootstrap и восемь exports iron3d.dll.
Карта 15 DLL, exports/imports и основные interface boundaries.
NRes layout, поиск и writer rules.
RsLi header, table transform, lookup, mapping и используемые decode paths.
TMA всех 60 проверенных миссий, unit DAT и objects.rlb resolution.
MSH core/animation range contracts.
WEAR, MAT0, Texm и FXID framing.
Land.msh/Land.map и areal grid.
World3D calculation/render order и deferred deletion.
Сквозная mission-to-texture цепочка.

Полная проверка доступных каталогов усилила NRes active ranges, recursive prototype inheritance через objects.rlb, bounded non-NUL unit descriptions, полный TMA epilogue, extra records и Clan mode 0, MSH/MAT0/Texm/FXID variant matrix Частей 1 и 2, 65 Land.msh/Land.map, полный reachable graph 60 миссий, stability matrix пятнадцати DLL, empty SWAV и stale save-slot metadata.

Render-state и pixel parity

Доказан порядок frame boundaries, world traversal, material resolve и крупных проходов. Не доказаны символами точные названия renderer vtable slots +0x28/+0x30/+0x34, полный набор state transitions CShade и окончательный взаимный порядок некоторых transparent/FX/shadow subpasses.

Pixel parity требует эталонных кадров оригинала с фиксированными camera, timing, seed, разрешением и capability profile. Вместе с изображением необходимо сохранять command/state trace; иначе pixel difference не позволяет отличить ошибку формата от ошибки backend-а.

Минимальный capture должен фиксировать resolution, bit depth, selected driver, device capabilities, camera matrices, mission, game time, seed, input log, scene boundaries, transforms, render states, texture-stage states, texture binds, viewport, clear, draw calls и Blt/Flip. Сначала сравниваются command lists; pixel diff имеет смысл только после совпадения geometry/state sequence.

FXID field-level semantics

Размеры команд, resource references, lifecycle, flags families и используемые time modes известны. Не закрыто значение каждого поля body opcodes 1-10, отсутствующий во всех проверенных каталогах opcode 6 и точные формулы редких time modes.

Закрывающий эксперимент: создать инструмент, который изменяет по одному полю копии эффекта, воспроизводить его в контролируемой сцене и логировать runtime command object, emitted primitives и sound events. Одновременно reads в Effect.dll сопоставляются с offsets body.

Script VM

Сценарные packages, symbol names, event sections, variable declarations и version check доступны. Полная instruction grammar .scr, semantics всех opcodes и serialization состояния VM ещё не восстановлены.

План реконструкции:

Найти loader .scr, version check, границы bytecode, таблицы strings/symbols/events.
Найти dispatcher loop по повторяющемуся чтению opcode и indirect branch или jump table.
Для каждого handler определить instruction size, operands, чтения/записи VM state, stack effect, branch target и world side effects.
Hook-нуть dispatcher и писать запись package,event,ip,opcode,raw operands,state before,state after,next ip.
Построить disassembler и CFG; branch target обязан попадать на подтверждённую границу инструкции.
Закрывать opcode после статического handler contract, одного динамического trace и одного regression script.

После opcode table отдельно восстанавливаются serialization IP, call/event frames, variables, timers и RNG.

Physical/control formats

CTLD и связанные resources структурно читаются, count patterns и variants известны. Не названы все секции, shape types, coefficients и точный contact solver. То же относится к редким MSH types 17/20 и части CTPT/NDPR flags.

Закрывающий эксперимент: трассировать LoadControlSystem, LoadPhysicalModel и создание collision objects на нескольких прототипах; записать offsets, созданные shape instances и реакции на контролируемое движение. Изменение одного resource field должно связываться с одним наблюдаемым параметром.

Сеть

DirectPlay lifecycle и имена игровых сообщений известны. Точные framing, payload schema, reliability flags и алгоритм netZipData пока не подтверждены записью сетевого обмена. Поэтому совместимость с оригинальным сетевым клиентом ещё не доказана.

Для закрытия нужны два оригинальных клиента в изолированной среде и логирование netZipData, netUnZipData, DirectPlay Send/Receive и World3D message enqueue/dequeue. Native interoperability подтверждается только успешным обменом original client <-> compatibility implementation в обе стороны.

Редкие или отсутствующие corpus-ветки

Land.map poly_count > 0: layout читается из loader-а, но ни одна из 65 проверенных карт не содержит живой записи.
RsLi adaptive methods 0x080/0x0A0: decoder path известен, однако демоверсия и обе полные части их не используют.
Texm formats 556 и 88: loader поддерживает их, но ни один проверенный Texm не использует эти значения.
FX opcode 6: размер известен, однако живой command отсутствует во всём доступном corpus.
Некоторые material flags и MSH auxiliary streams встречаются слишком редко для полного authoring contract.

Такие ветки реализуются строго по бинарному коду и synthetic tests, а статус corpus-verified получают только после появления реального файла.

Сохранения и campaign state

saveslots.cfg и missions/dispatcher.ini найдены, но полный бинарный savegame payload, serialization World3D/AI/script/RNG и правила миграции версии не восстановлены. Без этого нельзя честно заявлять полную campaign compatibility.

Минимальный набор сохранений для каждой части:

S0  сразу после старта миссии
S1  тот же state без simulation step
S2  изменена только позиция одного объекта
S3  изменено только здоровье/свойство
S4  активен один Behavior order/path
S5  активен один FX и timer
S6  изменена одна script variable
S7  изменён research/economy state
S8  перед/после mission completion
S9  pause и non-default game time

Без самих binary save payload возможно описать обязательный state и найти код сериализации, но невозможно доказать disk layout и roundtrip.

Shell, HUD, шрифты и локализация

Граница shell подтверждена экспортами createShell/getIShell, IGUIServer, верхнеуровневым UI-pass и файлами ui/*.cfg, DATA/TextRes.cfg, gamefont.rlb и sprites.lib. RsLi framing двух библиотек закрыт, но widget tree, layout rules, font glyph metrics, sprite command semantics, focus/navigation и полный HUD state machine пока не восстановлены до field-level спецификации.

До закрытия новая реализация может построить функционально эквивалентный UI поверх известных ресурсов, но не заявлять native layout/behavior parity.

Исследования, экономика и игровые свойства

Экспорты LoadResearch, CalcFullResearchCost, TRF/preload resources и TMA properties доказывают отдельный слой исследований, стоимости, добычи и производственных параметров. Сквозные имена (MaximumOre, CurrentOre, FreeResearchTime, FreeConstructionTime и другие) доступны, однако формулы стоимости, dependency graph технологий, inventory/economy transitions и точная типизация всех 16-byte property values не закрыты.

Закрывающий эксперимент: сопоставить LoadResearch/CalcFullResearchCost с ресурсами и UI, снять изменения state на контролируемых покупках/исследованиях и построить typed schema свойств по consumers, не по одному имени.

Условия динамического этапа

Полное закрытие оставшихся вопросов технически возможно, но не только по статическим архивам. Нужна среда, способная запускать оригинальный 32-битный код, и набор эталонных наблюдений:

Изолированная 32-битная Windows VM или отдельная машина с исходными DirectDraw/Direct3D/DirectSound/DirectPlay interfaces.
Два неизменённых игровых каталога и manifest SHA-256 для executable, DLL, конфигураций и ключевых архивов.
Отладчик с hardware/software breakpoints, просмотром x87/SSE state и сохранением memory dumps.
API/vtable hooking для Win32 file I/O, DirectDraw/Direct3D, DirectSound и DirectPlay; hooks должны писать binary trace, не изменяя порядок вызовов.
Управляемые clocks, input log и RNG seed либо trace всех вызовов источника случайности.
Автоматический launcher, который восстанавливает snapshot VM, запускает один test case, собирает логи и завершает процесс без ручного вмешательства.

Для каждого capture сохраняются profile сборки, hash модулей, mission/resource key, конфигурация, device profile, начальное состояние, input/time script и версии инструментов.

Критерий закрытия открытого вопроса

Для каждого открытого вопроса должны существовать:

build fingerprint и адреса наблюдаемых функций;
raw trace и автоматический parser trace-а;
минимальный воспроизводимый input/resource/save/message;
формальный контракт или явно ограниченная гипотеза;
differential test для Частей 1 и 2, если модуль изменён;
обновление тематической статьи;
regression case, запускаемый без ручного анализа.

До выполнения этих условий статический контракт пригоден для реализации, но утверждение о полном поведенческом или native-паритете не публикуется.

Глоссарий

Бинарные файлы и reverse engineering

PE (Portable Executable) -- формат исполняемых файлов Windows: EXE и DLL. Он содержит заголовки, секции, таблицы импортов и экспортов, relocations и адрес точки входа.

Image base -- предпочтительный адрес начала загруженного PE-образа. VA -- виртуальный адрес в процессе. RVA -- адрес относительно image base. Адрес функции в памяти обычно равен image_base + RVA.

Import -- внешняя функция или переменная, которую модуль получает из другой DLL. Export -- символ, предоставляемый другим модулям. Имя, ordinal и calling convention вместе образуют часть бинарного контракта.

ABI -- соглашение о двоичном взаимодействии: размещение аргументов, возврат значений, очистка stack, layout структур, порядок virtual methods и правила владения.

Calling convention -- часть ABI, определяющая передачу аргументов и очистку stack. Для исследованного 32-битного кода важны __cdecl, __stdcall и __thiscall.

Vtable -- массив указателей на virtual methods C++-объекта. Запись vtable +0x34 означает вызов указателя по байтовому смещению 0x34 от начала таблицы.

Static analysis исследует файл без его исполнения: disassembly, strings, imports, call graph и data flow. Dynamic analysis наблюдает работающую программу: breakpoints, traces, API hooks, memory state и packet/frame captures.

Evidence -- наблюдение, которое можно повторить. Inference -- вывод, объединяющий несколько наблюдений. Hypothesis -- рабочее предположение, ещё не подтверждённое достаточным экспериментом.

Форматы данных и ресурсы

Archive -- контейнер, объединяющий множество ресурсов. Entry -- запись его каталога. Payload -- полезные bytes конкретной записи.

Magic -- короткая сигнатура формата, например NRes или Texm. Version -- номер варианта layout. Проверка одной magic без проверки version и размеров недостаточна.

Offset -- положение данных относительно начала файла или структуры. Size -- число занимаемых bytes. Stride -- размер одного элемента массива. Alignment -- требование начинать данные на address или offset, кратном заданному числу.

Little-endian -- порядок, в котором младший byte многобайтного числа расположен первым. Все основные числовые поля исследованных форматов Iron3D используют этот порядок.

Fixed-size string -- поле заранее известной длины. Полезная строка заканчивается первым NUL, но оставшиеся bytes поля могут содержать служебный хвост и должны сохраняться.

Opaque field -- поле с доказанными offset и размером, но не установленным предметным смыслом. Его безопасно читать и копировать, но нельзя очищать или переосмысливать без эксперимента.

Invariant -- условие, которое обязано выполняться: диапазон находится внутри payload, индекс указывает на существующий элемент, число записей соответствует размеру секции.

Strict reader отклоняет любое нарушение контракта. Compatibility reader дополнительно воспроизводит только известные особенности оригинала, например именованный fallback. Compatibility mode не означает игнорирование произвольной порчи.

Roundtrip -- последовательность decode -> encode. Byte-identical roundtrip создаёт файл, полностью совпадающий с исходным. Lossless editor может изменить известное поле, сохранив все остальные bytes и порядок записей.

Fallback -- явно предписанный запасной путь, например материал DEFAULT, затем entry 0. Heuristic -- догадка по похожим данным; она не должна незаметно заменять доказанный fallback.

Игровой runtime

Engine -- программная среда, которая загружает данные, ведёт время, исполняет мир и формирует изображение/звук. Game -- конкретные правила, миссии и содержимое, работающие поверх engine services.

World -- долгоживущее состояние миссии: objects, terrain, время, кланы и managers. Scene -- представление части мира для конкретной обработки, чаще всего текущей камеры.

Game object -- сущность с идентичностью, transform, properties и lifecycle. Component/controller -- специализированная часть поведения: animation, physics, AI или rendering representation.

Simulation отвечает за изменение мира. Tick -- один расчётный шаг simulation. Frame -- одно подготовленное изображение. Число ticks и frames за единицу времени не обязано совпадать.

Game loop -- повторяющийся порядок ввода, расчёта, рендера и обслуживания. Scheduler phase -- явно ограниченный участок loop, где разрешены определённые операции.

Event/message -- типизированное сообщение между objects или subsystems. Queue traversal -- стабильный обход зарегистрированных объектов. Deferred deletion -- перенос фактического удаления до безопасной границы после traversal.

Determinism -- одинаковый результат при одинаковом initial state, input, времени и порядке событий. Replay -- повторное исполнение записанной последовательности входов/сообщений для проверки determinism.

Authority -- subsystem или network peer, которому разрешено окончательно менять состояние объекта. Mirror object -- локальное представление объекта, authority которого находится у другого player.

Геометрия, анимация и рендеринг

Mesh -- набор vertex/index streams и draw-групп, описывающий форму. Node -- элемент hierarchy модели со своим local transform. Slot в MSH -- выбранная геометрическая группа для комбинации node, LOD и group; он также хранит bounds и диапазоны batches.

Batch -- непрерывный индексный диапазон с одним material slot и общим render state. Transform переводит данные между local, world, view и clip spaces. Порядок умножения matrices является частью контракта.

Quaternion -- четырёхкомпонентное представление вращения. Keyframe -- pose в определённое время. Sampling выбирает pose для времени, а blending смешивает animation states.

Bounds -- упрощённый объём для быстрых тестов. AABB -- пара minimum/maximum по осям. Bounding sphere -- center и radius.

Renderer -- subsystem, преобразующая подготовленную сцену в изображение. Backend -- реализация renderer поверх конкретного API или устройства.

Draw call -- команда нарисовать диапазон primitives с текущими resources и states. Material -- правила отображения поверхности: texture, коэффициенты, прозрачность и режимы pipeline. Material phase -- одно временное состояние анимированного материала.

Texture -- двумерный массив texels. UV coordinates -- координаты выборки. Mip chain -- последовательность уменьшенных уровней texture. Lightmap -- texture с заранее рассчитанным вкладом освещения.

Fixed-function pipeline -- старый графический pipeline, где приложение выбирает predefined transform, lighting, texture-stage и blend states вместо пользовательских shaders.

Depth buffer хранит глубину уже принятой поверхности. Alpha test полностью принимает или отвергает fragment. Blending смешивает новый цвет с framebuffer.

Back buffer -- скрытый framebuffer. Present/flip делает завершённый кадр видимым. Pixel parity -- совпадение конечного изображения при фиксированных условиях.

Навигация, физика, звук и сеть

Areal -- логическая область карты с границей, class/flags и связями с соседями. Areal graph -- граф, вершинами которого служат области, а рёбрами -- допустимые переходы. Cell grid -- пространственный индекс для candidate areas или objects.

Pathfinding -- поиск маршрута по графу. A* использует стоимость уже пройденного пути и оценку расстояния до цели. Навигационная проходимость, отсутствие collision и видимость -- разные свойства.

Collision proxy -- упрощённое представление объекта для столкновений. Broad phase быстро находит потенциальные пары; narrow phase выполняет точную проверку и вычисляет contact.

Sample -- декодированные звуковые данные. Source -- экземпляр воспроизведения с position, gain, loop state и временем. Listener -- позиция и ориентация слушателя для 3D spatialization.

Transport -- механизм доставки bytes между peers. Protocol -- framing, message types, порядок и правила подтверждения. Serialization -- преобразование typed state в byte sequence.

Reliable delivery гарантирует доставку/порядок в пределах выбранной модели; unreliable delivery допускает потери ради задержки. Wire compatibility -- способность обмениваться данными с оригинальным клиентом, а не только воспроизводить ту же игровую семантику в новом протоколе.

Связанные локальные справки

Дополнительное чтение

Эти материалы помогают понять PE, ABI, сжатие, graphics pipeline, game loop и навигацию. Они не являются доказательством поведения Iron3D: детали движка принимаются только после проверки его бинарного кода и игровых ресурсов.

57 KiB Raw Blame History Unescape Escape

VIII. Справочник и доказательная база

Как читать доказательства

ABI и границы модулей

Базовый binary profile

Публичная поверхность DLL

Композиционный и сервисный слой

Предметные фабрики

World3D export families

Net и Joystick

Ngi32 export families

Подтверждённые RVA

Vtable и interface negotiation

ABI-матрица Частей 1 и 2

Файловая поверхность

Каталог как внешний API

Iron_3D.ini

Comp.ini: реестр компонентов

Behavior.ini и ArealMap.ini

Миссии, UI и сохранения

Правила файловой совместимости

Различия файловой поверхности Частей 1 и 2

Результаты проверки корпусов

Demo baseline

Миссии и сквозные ссылки

Реестр и unit DAT

Модели

Материалы и текстуры

Эффекты

Карты

Вспомогательные форматы

Как читать статистику

Полные каталоги Частей 1 и 2

Границы знания

Закрытые или практически закрытые области

Render-state и pixel parity

FXID field-level semantics

Script VM

Physical/control formats

Сеть

Редкие или отсутствующие corpus-ветки

Сохранения и campaign state

Shell, HUD, шрифты и локализация

Исследования, экономика и игровые свойства

Условия динамического этапа

Критерий закрытия открытого вопроса

Глоссарий

Бинарные файлы и reverse engineering

Форматы данных и ресурсы

Игровой runtime

Геометрия, анимация и рендеринг

Навигация, физика, звук и сеть

Связанные локальные справки

Дополнительное чтение

57 KiB

Raw Blame History

`Iron_3D.ini`

`Comp.ini`: реестр компонентов

`Behavior.ini` и `ArealMap.ini`