fparkan/docs/appendices/script-vm.md

Сценарная VM, формулы и игровые свойства

Подтверждённый surface

Миссионный сценарный слой задаёт стартовые события, completion/failure, messages, teleports, задачи, research и campaign transitions. Точки входа и файлы: ai.dll: CreateSuperAI/GetSuperAI, MisLoad.dll: LoadResearch, ArealMap.dll: CalcFullResearchCost, MISSIONS/SCRIPTS/*.scr, *.fml, *.trf, varset.var, MISSIONS/dispatcher.ini, mission.cfg, messages.cfg и briefing.cfg.

.scr — binary package с version checks, symbol/event sections и offsets; полная opcode grammar не доказана. Его внешний framing теперь читает fparkan-script: первый little-endian u32 является числом required opcode handlers, второй — числом event records. Каждый event хранит name_len, name_len + 1 raw bytes с обязательным NUL, opaque event word и count вложенных records. Вложенный record сохраняет семь u32 header words (в disk order), список u32 references после шестого header word и trailing seventh word. Никакой из этих words ещё не получает semantic name. .fml — текстовый symbol/formula oracle; varset.var задаёт VAR(...)/STRING(...) defaults; .trf — NRes tables, чей framing подтверждён, а field semantics местами лишь consumer-inferred.

Безопасная модель исполнения

Новая VM разделяет immutable package (bytecode, symbols, events, constants), per-mission variables/timers/frames, bindings logical-name/ObjectId/clan/ research key и typed commands к World3D/Behavior/UI/campaign. После varset defaults и bindings она dispatches Init/start, на каждом tick обновляет timers, ставит готовые events в стабильную очередь и исполняет bounded instruction budget. Опасное удаление идёт через World3D queue и общий deferred lifecycle.

До восстановления 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.

GOG ai.dll доказывает этот framing двумя consumer-ами: loader по 0x10001000 открывает <bundle>.scr, varset.var, <bundle>.fml, затем собирает ровно 73 pointers handlers; 0x10011b20 читает описанную count-driven структуру. Команда

cargo run -p fparkan-cli -- script inspect `
  'C:\GOG Games\Parkan - Iron Strategy\MISSIONS\SCRIPTS\c1m2p.scr' --format json

на исходном пакете возвращает opcode_handler_count=73, 9 events, 17 nested records, 20 references и 0 trailing bytes. Это corpus evidence для reader-а, но не разрешение на исполнение неизвестных 73 opcodes.

Теперь установлен selector: loader 0x10001000 создаёт 73 pointers в фиксированном порядке, а 0x10011e70 копирует их без перестановки в runtime array. Во всех 58 GOG .scr первый header word каждого nested record равен 0..72 либо 0xffff_ffff: соответственно 2095 handler selectors и 3992 sentinel records. Поэтому ScriptInstruction::dispatch_selector() возвращает Handler(0..72), Sentinel или сохраняемый Unknown(u32). Первый handler (Handler(0), VA 0x10008034) только устанавливает current context и flag +0x50 = 1; это не даёт ему игрового имени и не заменяет runtime trace.

TMA properties остаются four raw u32 words плюс имя, пока consumer/schema не задаст тип (integer/float bits/ObjectId/enum/fixed-point/index). В том числе сохраняются NOT USED; corpus подтверждает Invulnerability, life state, ClanID, ore, speed и free-time properties.

Research/economy работают в simulation: LoadResearch и CalcFullResearchCost доказывают данные и вычислимую стоимость, но не полный layout prerequisites/modifiers/unlocks. Formula evaluator требует strict grammar/version, typed operands, deterministic numeric policy, bounded stack и явных errors; x87-compatible rounding нужен там, где оно выбирает ветку.

Готовность

Все demo packages должны проходить package/version checks, offsets оставаться в bytecode, а confirmed disassembler — не терять синхронизацию. VM считается готовой после deterministic Init/basic mission events, stable object bindings, typed research/property tests и save/load script state. Для закрытия остаются dispatcher/jump table, minimal differential packages и traces world/variable effects; до них unknown opcode — явная unsupported branch, не no-op.