aboutsummaryrefslogtreecommitdiff
path: root/docs/tomes/06-behavior.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/tomes/06-behavior.md')
-rw-r--r--docs/tomes/06-behavior.md167
1 files changed, 163 insertions, 4 deletions
diff --git a/docs/tomes/06-behavior.md b/docs/tomes/06-behavior.md
index 125f0d5..2b26f62 100644
--- a/docs/tomes/06-behavior.md
+++ b/docs/tomes/06-behavior.md
@@ -542,10 +542,169 @@ component как ordered raw-string/resource provenance, но не для при
этим строкам смысловых имён до трассировки private update methods.
Runtime сохраняет ordered raw Unit DAT records рядом с каждым mission object
-draft. Это создаёт проверяемую границу передачи данных от loader-а к будущему
-Control consumer-у: никакой компонент пока не получает имя `Control` только
-по `kind`, `parent_or_link` или description; semantic binding появится лишь
-после trace private update/load methods.
+draft. Теперь подтверждена связь Unit DAT с descriptor-ом AniMesh, который
+передаётся в Control: порядок узлов задаётся деревом immediate-child counts,
+а `parent_or_link` попадает в descriptor как локальное поле. Его смысл зависит
+от registry type и состояния Control manager-а; в частности, для `INTO` это
+локальный индекс устройства, а `EXTO` проходит отдельную ветвь.
+
+### От Unit DAT к Control descriptor
+
+В GOG `ArealMap.dll` (SHA-256
+`a25f9254ebb339d70e2e07c8121950191e9584ca0858d8e9c2e2b6c671edf6ea`)
+`FUN_10016a10` (RVA `0x16a10`) читает запись Unit DAT в дерево узлов по
+`0x78` байт: перед сырыми полями узла находятся указатель и количество детей,
+а байты файла копируются начиная с node `+0x0c`. `FUN_10015290` (RVA
+`0x15290`) передаёт каждый непосредственный узел корня в `FUN_10014b90`
+(RVA `0x14b90`) с начальным parent ID `0`.
+
+Для узла с ненулевым raw kind `FUN_10014b90` формирует descriptor размером
+`0x4c`: две строки ресурса копируются из node `+0x0c` и `+0x2c`, поле
+descriptor `+0x40` получает parent ID, `+0x44` — DWORD node `+0x50`, а
+`+0x48` начинается со значения `-1`. Из-за смещения raw-полей на `0x0c`
+node `+0x50` — это ровно `parent_or_link` по смещению `0x44` в записи Unit
+DAT. Затем `ArealMap` посылает owner-у событие `6 / 0x80000020` через vtable
+slot `+0x34`.
+
+В `AniMesh.dll` (SHA-256
+`65659bf67f20e5be77d67a5b2f59968f61b94293143807fa59ca451c560c4f7e`)
+dispatcher `FUN_10001370` (RVA `0x1370`) передаёт это событие в
+`FUN_10003760` (RVA `0x3760`). Тот выбирает следующий свободный ID, записывает
+его в descriptor `+0x48` и сохраняет descriptor в списке компонентов.
+Вернувшись после virtual call, `FUN_10014b90` передаёт этот ID как parent ID
+рекурсивного обхода детей. Поэтому родительская связь Control descriptor-а
+строится по фактически назначенному ID в обходе дерева, а локальный индекс
+устройства приходит из `parent_or_link`.
+
+У этого обхода есть ранний выход: если raw kind в node `+0x4c` равен нулю,
+узел и его дети пропускаются. AniMesh начинает со служебного root ID `0`, но
+из-за пропусков и других записей назначенный ID нельзя в общем случае считать
+равным индексу узла или номеру его записи в Unit DAT.
+
+Для registry type `INTO` и других не-`EXTO` значений `FUN_10003760` разрешает
+parent ID через Control IID `0x202`, virtual slot `+0x44`, только если parent ID
+не равен `-1` и интерфейс IID `0x202` доступен. `Control.dll`
+`FUN_1002ecc0` (RVA `0x2ecc0`) возвращает индекс первого устройства, чьё поле
+`+0x08` равно этому ID, или `-1`, если совпадения нет; AniMesh прибавляет
+возвращённое значение к локальному индексу `+0x44` без отдельной проверки
+`-1`. Если parent ID равен `-1` или IID `0x202` недоступен, используется сам
+локальный индекс без смещения. Отсутствие устройства с parent ID — отдельный
+случай: native path даёт индекс на единицу меньше локального, и Rust-проекции
+нужно проверить это поведение явно. `EXTO` проходит отдельную ветвь, поэтому
+это правило нельзя распространять на все registry types.
+
+Ветка `EXTO` заполняет другие поля. В `FUN_10003760` RVA `0x3760` и mount
+`C4`, и target `C8` сначала равны `-1`. Ветка `EXTO` вычисляет mount и
+записывает его только в `C4`; `C8` остаётся `-1`. Поэтому Control добавляет
+все typed records такого компонента в конец общей таблицы. Raw
+`parent_or_link` здесь выбирает mount-узел, а не строку Control.
+
+`AniMesh.dll` (SHA-256
+`65659bf67f20e5be77d67a5b2f59968f61b94293143807fa59ca451c560c4f7e`)
+собирает глобальную нумерацию MSH-узлов: обычная корневая модель добавляет все
+`N` узлов, `EXTO`-дочерняя модель добавляет `N - 1`, начиная со своего узла `1`,
+а `INTO`-компонент не добавляет узлов. `FUN_1000a460` (RVA `0xa460`) выполняет
+эту загрузку MSH; `FUN_10005780` (RVA `0x5780`) находит первый глобальный узел
+с заданным component ID. Если у `EXTO`-модели только один узел, она не добавляет
+глобальных узлов, и поиск первого узла возвращает `-1`.
+
+При добавлении `EXTO` Control отдельно переводит ключи CTLD в пространство
+глобальной MSH-иерархии: нулевой ключ заменяется mount-узлом `C4`; ненулевой
+ключ сдвигается относительно первого глобального узла компонента только при
+`C4 != -1`. Например, если компонент начинается с глобального узла `22`, его
+исходный ключ `1` становится `22`. Этот ключ выбирает модельный узел, а не
+строку Control. Записи корня остаются в исходном виде.
+
+### Как Control добавляет и переопределяет устройства
+
+В `Control.dll` (SHA-256
+`bcb86318089028548a178b03a21accdce15df0cc85ddd91674cf3c2f55012c6e`)
+`FUN_10008b10` (RVA `0x8b10`) выбирает путь по полю descriptor `+0xc8`.
+Значение `-1` запускает цикл по typed records; фабрика `FUN_1002d4b0` (RVA
+`0x2d4b0`) создаёт по устройству на запись и сохраняет их порядок. Иное
+значение вызывает `FUN_1002d890` (RVA `0x2d890`) только один раз; цикл по
+typed-record count в этой ветви отсутствует. Следовательно, подтверждённый
+override path применяет первую typed record и не добавляет новый объект.
+Так модуль меняет характеристики уже существующего слота, не увеличивая число
+устройств. Неизвестный tag в Rust CTLD parser приводит к `Unsupported` и может
+оставить typed-record list неполным. Native factory имеет отдельный default
+путь `0x20800`, поэтому такой результат парсера сам по себе не доказывает отказ
+оригинального loader-а и не позволяет объявить Rust merge полным.
+
+FParkan строит базовую проекцию этой таблицы во время полного mission load для
+объектов с Unit DAT. Корневые typed records добавляются в исходном порядке;
+`EXTO` тоже добавляет все свои записи с remapped MSH-ключами; `INTO` обновляет
+одну строку по `C8`, а при sentinel `-1` добавляет весь список. Preview таблицу
+не создаёт. Проекция хранит исходный factory tag, текущий typed record и их
+provenance, но не исполняет все tag-specific callbacks и не заменяет полный
+Control runtime. Лицензированный `UNITS/BUILDS/MINE/min_l_n1.dat` подтверждает
+10 исходных устройств, четыре `INTO`-override по индексам `0..3` и добавление
+одной дочерней записи `EXTO` с ключом `22`, всего 11 устройств. Это результат
+Rust full-loader теста на оригинальных ресурсах. Ветви C4/C8 и добавление
+`EXTO` подтверждены статически по native ASM; отдельный native full-load oracle
+для всей таблицы не запускался.
+
+Для tag `19` фабрика создаёт объект с его исходными классом и vtable. Базовый
+конструктор `FUN_100218b0` задаёт multiplier `+0x4c = 1.0`. Override через
+`FUN_1002d890` вызывает у выбранного объекта vtable slot `+0x1c`, то есть
+`FUN_10021d50` с флагом инициализации `0`. Этот вызов не создаёт объект и не
+заменяет класс или vtable. Он сохраняет уже существующий ключ `+0x04`; сохраняет
+текущее значение multiplier `+0x4c` (которое могло измениться после
+конструктора); и копирует коэффициенты из CTLD в блок `+0x54`. Поле `+0x50`
+обновляется лишь когда слово записи `+0x18` не равно `-1`. Сопоставленные
+записи значений прибавляются к текущим полям объекта `+0x1c/+0x20`, а не
+сбрасывают их. Поэтому «переопределение» здесь означает обновить часть данных
+того же устройства, с ограничениями конкретного метода.
+
+Native x86 oracle для тех же GOG DLL выполняет конструкторы и этот общий setter
+на уже созданных получателях factory tags `9`, `15`, `19` и `25` (размеры
+объектов `0x120`, `0x98`, `0x94` и `0xa4`). У всех проверенных vtable slot
+`+0x1c` указывает на RVA `0x21d50`; тест подтверждает, что override сохраняет
+существующий слот, класс/vtable, ключ, component ID и multiplier `2.5`, копируя
+новые коэффициенты. Slot `+0x24` у tag `9` указывает на отдельный обработчик
+`0x25600`, а у остальных трёх — на no-op `0xbcd0`. Tag `9` проверяется с
+нулевым pointer `+0x3c` и записью без map rows: FX host намеренно не подключён,
+поэтому его поведение этим опытом не подтверждено.
+
+Статический разбор глобального Control interface показывает aggregate getters
+`1/2` (`FUN_1002b410`, RVA `0x2b410`) и setter `1` (`FUN_1002ba30`, RVA
+`0x2ba30`) для текущего descriptor tag `19`. Getter `1` складывает ответы
+виртуального selector `0x200` в числитель и selector `0` в знаменатель; getter
+`2` возвращает сумму selector `0`. Для обычного factory tag `19` эти ответы
+равны `coefficient * multiplier` и `coefficient`, то есть отношение сводится к
+`sum(coefficient * multiplier) / sum(coefficient)`. У factory tag `9` selector
+`0` умножает коэффициент на отдельное поле `+0x11c`, тогда как selector `0x200`
+использует коэффициент и multiplier; эта особая база меняет знаменатель.
+Обработчик factory tag `9` расположен в Control RVA `0x255c0`, а его конструктор
+RVA `0x25460` задаёт `+0x11c = 1.0`. При встрече отрицательного ответа selector
+`0` getter `1` сразу возвращает `1.0`, а getter `2` — этот ответ. Если подходящих
+записей нет или сумма базы неположительна, getter возвращает неуспех без записи
+результата. Setter пишет multiplier `+0x4c` только устройствам с текущим
+descriptor tag `19` и положительным selector-0 ответом; пустой набор возвращает
+успех. Фильтр использует **текущий descriptor tag**, который может измениться
+при `INTO`, а виртуальный вызов остаётся методом исходного factory-класса.
+
+Этот путь проверяется native x86 oracle на оригинальной `Control.dll` указанной
+выше: искусственные factory/descriptor пары `9`, `15` и `19` покрывают setter,
+отрицательные ответы, округление и тег `9` с scale `0.5`. Для factory tag `25`
+его vtable slot `+0x10` статически указывает на общий getter RVA `0x21d00`, но
+отдельный aggregate oracle этот класс не запускал. Rust хранит начальный scale
+factory `9` и предоставляет `query_loaded_mission_control_resource` для selector
+`1`/`2` и `set_loaded_mission_control_multiplier` для setter-а `1`. Вызовы
+сначала проверяют живой `ObjectHandle`, затем обращаются к таблице этого объекта
+из полной загрузки миссии. Синтетические тесты проверяют границы пустой таблицы,
+нулевого знаменателя, неподдержанных factory tags и чисел за диапазоном
+нормального `f32`; лицензированный тест сверяет реальные descriptor tags и
+получает для `min_l_n1.dat` сумму `16` и отношение `1` до setter-а.
+
+В этом API пока реализованы только getter selectors `1`/`2` и setter `1`.
+Отдельный native setter selector `17`, tag-specific методы прочих factory tags,
+их внешние эффекты и вызов из регулярного шага Behavior здесь не моделируются.
+Числа должны оставаться конечными и нормальными либо точным нулём; произведения
+и отношения за поддерживаемым диапазоном `f32` возвращают явную ошибку, а не
+подменяются нулём или `None`. При проверке диапазона Rust оценивает операцию в
+`f64`, затем выполняет её в `f32`; это ограниченная проверка диапазона, а не
+эмуляция полного x87 accumulator-а.
Отдельная ветка того же GOG `AniMesh.dll` показывает, когда создаётся Behavior
для host object. В `FUN_10002ff0` (RVA `0x2ff0`, SHA-256