From 37db376dd3b259cfefdb7081770ca82bdc7542dd Mon Sep 17 00:00:00 2001 From: Valentin Popov Date: Tue, 20 Oct 2026 01:45:58 +0400 Subject: docs(script): describe native condition evaluation --- docs/appendices/knowledge-boundaries.md | 18 ++++++- docs/appendices/script-vm.md | 86 ++++++++++++++++++++++++++++++--- docs/tomes/06-behavior.md | 66 +++++++++++++++++-------- 3 files changed, 144 insertions(+), 26 deletions(-) diff --git a/docs/appendices/knowledge-boundaries.md b/docs/appendices/knowledge-boundaries.md index 661069a..ad7bc13 100644 --- a/docs/appendices/knowledge-boundaries.md +++ b/docs/appendices/knowledge-boundaries.md @@ -31,9 +31,25 @@ primitives, sound events и reads в `Effect.dll`. checks. Полная instruction grammar `.scr`, semantics opcodes и serialization state ещё не восстановлены. +Для GOG `ai.dll` статически восстановлены пять ветвей evaluator-а 16-byte +записей условий по RVA `0x5180`, включая проверки типов, поиск объектов, +короткие выходы из обхода списков и запись байта завершения. Однако не найден +код-производитель этого массива и контракт его владельца с runtime. Reader +`FUN_10011b20` хранит описатели событий и вложенных записей `.scr` во внутренних +контейнерах с шагом `0x14` и `0x20`; сами дисковые структуры имеют переменную +длину из-за length-prefixed имён и списков ссылок. Связь этих контейнеров с +массивом evaluator-а не доказана. Виртуальные методы, +через которые проходят проверки, остаются внешней границей, а сам evaluator +не сравнивался с работающим оригиналом. Описание этих ветвей — статический +вывод по одному известному `ai.dll`, а не утверждение о совпадении во время +исполнения. + Закрывающий эксперимент: найти dispatcher loop в `ai.dll`, сопоставить jump table с instruction sizes, построить disassembler и сравнить выполнение -коротких scripts с оригиналом. +коротких scripts с оригиналом. Для evaluator-а условий отдельно проследить +создание записей `this + 0x34`, выполнить те же входные данные в оригинале и +сверить байт завершения, порядок поиска, ранние выходы и граничный случай +`payload == count`. ## Saves and campaign state diff --git a/docs/appendices/script-vm.md b/docs/appendices/script-vm.md index 0e0217f..50e0f2b 100644 --- a/docs/appendices/script-vm.md +++ b/docs/appendices/script-vm.md @@ -42,12 +42,12 @@ budget. Опасное удаление идёт через World3D queue и о До восстановления opcode table package mode читает header/strings/symbols/ event offsets/raw bytecode losslessly. Статический анализ уже выделил отдельный -five-way evaluator condition records (`ai.dll` VA `0x10005180`): tags `1..5`, -type guards, object lookup и completion flag. Это не следует выдавать за -instruction dispatcher или jump table `.scr`: bytecode opcode table всё ещё -требует отдельного доказательства. Unknown opcode нельзя пропустить как один -byte: это ломает синхронизацию. Для каждого доказанного opcode фиксируются -number, size, operands, control flow, effects, errors и минимальный test. +evaluator записей условий (`ai.dll` RVA `0x5180`). Его подтверждённые ветви и +точные границы описаны ниже; он не является dispatcher-ом инструкций или jump +table `.scr`. Bytecode opcode table всё ещё требует отдельного доказательства. +Unknown opcode нельзя пропустить как один byte: это ломает синхронизацию. Для +каждого доказанного opcode фиксируются number, size, operands, control flow, +effects, errors и минимальный test. GOG `ai.dll` доказывает этот framing двумя consumer-ами: loader по `0x10001000` открывает `.scr`, `varset.var`, `.fml`, затем @@ -65,6 +65,80 @@ sentinel records. Поэтому `ScriptInstruction::dispatch_selector()` воз (`Handler(0)`, VA `0x10008034`) только устанавливает current context и flag `+0x50 = 1`; это не даёт ему игрового имени и не заменяет runtime trace. +### Evaluator записей условий: `ai.dll` RVA `0x5180` + +Ниже описан отдельный слой готовых условий, а не декодирование instructions. +Результат привязан к GOG `ai.dll` версии `1.00`, SHA-256 +`c19cd6cd31cd2896f8c4ba0f0e700dd3408aec8182daaf4863d98a7d233a2abc`; +PE image base — `0x10000000`, адрес функции — VA `0x10005180` / RVA `0x5180`. +Функция занимает 910 байт и имеет единственного прямого caller-а +`FUN_10004ee0` (RVA `0x4ee0`). Это статический вывод по машинному коду; сам +evaluator и его внешний объектный интерфейс здесь не запускались. + +Функция принимает signed index в массив записей по `this + 0x34`. Проверенный +доступ `FUN_100070c0` возвращает 16-byte запись: + +| Смещение | Поле | Роль в evaluator-е | +| ---: | --- | --- | +| `+0x00` | `u32 tag` | Выбор одной из пяти ветвей | +| `+0x04` | `u32 subtype` | Дополнительная проверка формата ветви | +| `+0x08` | payload | Ключ объекта или индекс списка, в зависимости от tag | +| `+0x0c` | byte completion | Записывается в `1` только после успешной проверки | + +Общие проверки допускают только пары `(tag 1..3, subtype 0)` и +`(tag 4..5, subtype 1)`. Неизвестный tag и неподходящий subtype не завершают +условие. При провале evaluator не очищает и не меняет байт завершения; при +успехе он устанавливает его в `1`. Вызывающая функция `0x4ee0` отдельно +пропускает уже завершённые записи, поэтому этот пропуск нельзя приписывать +самому evaluator-у. Прямая запись evaluator-а в запись — только этот байт, но +вызываемые виртуальные методы могут иметь внешние эффекты. + +Пары tag/subtype проверяются так: + +| Запись | Условие установки флага завершения | +| --- | --- | +| `(1, 0)` | Менеджер объектов, полученный из контекста `this + 0x60` по полю `+0x35c`, ищет payload через виртуальный слот `+0x1c`; поиск должен вернуть null. Найденный объект оставляет условие незавершённым. | +| `(2, 0)` | Поиск payload через тот же слот `+0x1c` должен найти объект. Затем его слот `+0x10` должен вернуть `0`, либо слот `+0x18` должен заполнить переданную структуру результата так, чтобы её первый `u32` был `1`, `0x12` или `0x13`. | +| `(3, 0)` | Поиск должен найти объект; его слот `+0x44` должен вернуть тот же `u32`, что и первый word контекста, на который указывает поле `this + 0x60`. | +| `(4, 1)` | Payload выбирает 32-byte запись в списке `this + 0x4c`; вложенный в неё список дочерних ссылок находится по смещению `+0x0c`. Ни один проверяемый дочерний ключ не должен разрешиться в объект. | +| `(5, 1)` | Используется тот же список. Отсутствующий объект пропускается; найденный объект проходит проверку, только если его слот `+0x10` вернул `0`. Первый найденный объект с ненулевым результатом завершает обход неуспехом. | + +Для tag 2 структура размером `0x138` байт инициализируется функцией +`FUN_10004330`, затем передаётся в slot `+0x18`. x87-значение, которое +возвращает этот вызов, инструкция `FSTP ST0` по RVA `0x5256` сразу удаляет со +стека FPU. Следовательно, ветвь принимает решение только по первому word +выходной структуры, а не по возвращённому числовому значению. + +У tag 4 и 5 есть важная граница индекса. Сравнение payload с количеством +элементов — unsigned `CMP` с условием `JA`: только `payload > count` сразу +оставляет запись незавершённой. Значение `payload == count` проходит эту +проверку и доходит до проверенного доступа `FUN_10002e20`; тот отвергает +`index >= count` и выбрасывает C++ exception. Это не эквивалентно обычной проверке +`payload < count` с безопасным отказом для всех неверных индексов. + +Сами дочерние ссылки списка читаются как signed `i32`. Ровно `-1` — sentinel, +который пропускается. Остальные значения проверяются как индексы в контекстном +массиве `context + 0x10` с 32-byte элементами; в элементе по `+0x04` берётся +ключ следующего поиска объекта. Для tag 4 первый найденный объект немедленно +прерывает обход с незавершённым результатом; для tag 5 обход прекращается на +первом найденном объекте с ненулевым результатом slot `+0x10`. Если обход +достигает конца без такого запрета, соответствующая ветвь устанавливает byte +completion. + +Из этих ветвей нельзя выводить языковые имена вроде «объект уничтожен» или +«объект принадлежит игроку»: в коде подтверждены только поиски, виртуальные +вызовы, сравнения и коды результата. Неизвестно и то, какая функция создаёт +массив 16-byte записей. Считыватель `FUN_10011b20` (RVA `0x11b20`) отдельно +разбирает `.scr` с переменной длиной: событие содержит длину и байты имени, +счётчик вложенных записей, а вложенная запись — семь заголовочных `u32` и список +ссылок. При разборе reader хранит описатели событий с шагом `0x14` и описатели +вложенных записей с шагом `0x20`; это шаги элементов внутренних контейнеров, а не +фиксированные размеры записей на диске. Связь этих контейнеров с массивом +`this + 0x34` не найдена, поэтому приравнивать их нельзя. Не установлены и +объект-владелец массива, соглашение его runtime-вызова и предметные эффекты +внешних виртуальных вызовов; границы перечислены в +[`knowledge-boundaries.md`](knowledge-boundaries.md). + `Handler(1)` — второй table entry, VA `0x10007fd0`, — не создаёт игровую команду. Он сохраняет active VM context, берёт один instruction-derived index через current event/instruction offsets `+0x48/+0x4c`, а затем разрешает его diff --git a/docs/tomes/06-behavior.md b/docs/tomes/06-behavior.md index d1af7ba..cd61533 100644 --- a/docs/tomes/06-behavior.md +++ b/docs/tomes/06-behavior.md @@ -181,25 +181,53 @@ IDs и отправляет команды через игровые interfaces, открытым направлением. До появления decompiler-а `.scr` binary body сохраняется lossless, а доказанные symbol/event tables документируются отдельно. -### Подтверждённый evaluator выражений - -Ghidra 12.1.2 decompile GOG `ai.dll` фиксирует отдельный evaluator по VA -`0x10005180` (не dispatcher инструкций `.scr`). Он получает индекс записи, -ищет её в контейнере `this + 0x34`, переключается по `u32 tag` в offset `+0` -и при успешном результате пишет completion byte в `+0x0c`. Из кода доказаны -ровно пять ветвей `tag = 1..5`; `tag = 1..3` требуют `u32` subtype в -`+0x04 == 0`, а `tag = 4..5` — `+0x04 == 1`. Поле payload находится по -`+0x08`. - -Ветки 1--3 делают lookup через object/interface, достижимый от -`this + 0x60 + 0x35c`, и используют его virtual slot `+0x1c`. Ветка 2 -дополнительно читает virtual slots `+0x10`/`+0x18` возвращённого объекта и -разрешает result tags `1`, `0x12`, `0x13`. Ветка 3 сравнивает virtual slot -`+0x44` с текущим object value. Ветки 4--5 используют `payload` как index в -контейнере `this + 0x4c`, обходят его child indices и делают тот же lookup; -их разные success-guards пока не именуются семантически. Это доказывает -typed condition/evaluation layer, но **не** формат `.scr`, размеры инструкций -или связь чисел tag с языковыми операторами. +### Подтверждённый evaluator записей условий + +У сценарного слоя есть не только последовательность инструкций, но и отдельные +короткие проверки состояния. В GOG `ai.dll` версии `1.00` evaluator таких +проверок расположен по RVA `0x5180` (VA `0x10005180` при image base +`0x10000000`; SHA-256 сборки — +`c19cd6cd31cd2896f8c4ba0f0e700dd3408aec8182daaf4863d98a7d233a2abc`). Он +получает индекс 16-byte записи и смотрит на её tag, subtype и payload. Для tags +1–3 допустим subtype `0`, для tags 4–5 — subtype `1`; другие сочетания не +завершают условие. Байт по смещению `+0x0c` — флаг завершения: evaluator ставит +`1`, когда проверка проходит, и оставляет запись как есть, когда не проходит. +Вызывающая функция позже пропускает уже завершённые условия. + +Tag выбирает конкретное правило. Для tag 1 запись завершается, когда поиск +объекта по payload ничего не нашёл. Для tag 2 объект, наоборот, должен +существовать: затем игра проверяет одно из его свойств и, в более сложной +ветви, принимает только три числовых кода результата — `1`, `0x12` и `0x13`. +Для tag 3 найденное значение сравнивается с первым числом текущего контекста. +Мы не знаем из одного этого кода, каким игровым словам соответствуют эти поля, +поэтому не называем их владельцем, жизнью или приказом. + +Теги 4 и 5 обходят дочерние ссылки выбранного списка. Значение `-1` означает +«элемента нет» и пропускается. Тег 4 завершается, только если ни один дочерний +ключ не нашёл объект. Тег 5 тоже пропускает отсутствующий объект, но для +найденного смотрит результат другого виртуального вызова: ноль разрешает +продолжить, а первый ненулевой результат прекращает обход и оставляет условие +незавершённым. Так различаются два алгоритма проверки набора объектов без +предположений о том, почему сценарист выбрал один из них. + +У списков обнаружена нетипичная граница. Программа сначала сравнивает индекс +списка с его длиной как unsigned число и отбрасывает только значения строго +больше длины. Равный длине индекс проходит первую проверку, но следующий +проверенный доступ обнаруживает выход за границу и возбуждает C++ exception. +Поэтому в будущем движке это нельзя незаметно заменить на «все неверные +индексы просто дают ложь». + +Это статическая реконструкция ветвей, а не доказательство исполнения условия +в работающем оригинале. Сам вызов RVA `0x5180` и внешний object interface не +проверялись динамически; неизвестен и код, который создаёт эти 16-byte записи. +Считыватель `.scr` хранит описатели событий и вложенных записей во внутренних +контейнерах с шагом `0x14` и `0x20` соответственно. На диске же `.scr` использует +переменные поля: имя события задаётся длиной, а вложенная запись содержит +заголовок и список ссылок. Связь этих структур с evaluator-ом не доказана. +Подробные смещения, +виртуальные слоты и границы анализа приведены в +[`приложении о сценарной VM`](../appendices/script-vm.md#evaluator-записей-условий-ai-dll-rva-0x5180) +и [`границах знаний`](../appendices/knowledge-boundaries.md#script-vm). ### TRF и preload-данные -- cgit v1.2.3