diff options
Diffstat (limited to 'docs/specs/fxid.md')
| -rw-r--r-- | docs/specs/fxid.md | 834 |
1 files changed, 834 insertions, 0 deletions
diff --git a/docs/specs/fxid.md b/docs/specs/fxid.md new file mode 100644 index 0000000..7dd1d4b --- /dev/null +++ b/docs/specs/fxid.md @@ -0,0 +1,834 @@ +# FXID + +Документ фиксирует спецификацию ресурса эффекта `FXID` на уровне, достаточном для: + +- 1:1 загрузки и исполнения в совместимом runtime; +- построения валидатора payload; +- создания lossless-конвертера (`binary -> IR -> binary`); +- создания редактора с безопасным редактированием полей. + +Связанный контейнер: [NRes / RsLi](nres.md). + +--- + +## 1. Источники и статус восстановления + +Спецификация восстановлена по: + +- `tmp/disassembler1/Effect.dll.c`; +- `tmp/disassembler2/Effect.dll.asm`; +- интеграционным вызовам из `tmp/disassembler1/Terrain.dll.c`; +- проверке реальных архивов `testdata/nres`. + +Ключевые функции: + +- parser FXID: `Effect.dll!sub_10007650`; +- runtime loop: `sub_10003D30(case 28)`, `sub_10006170`, `sub_10008120`, `sub_10007D10`; +- alpha/time: `sub_10005C60`; +- exports: `CreateFxManager`, `InitializeSettings`. + +Проверка по данным: + +- `923/923` FXID payload валидны в `testdata/nres`. + +--- + +## 2. Контейнер и runtime API + +### 2.1. NRes entry + +FXID хранится как NRes-entry: + +- `type_id = 0x44495846` (`"FXID"`). + +Наблюдение по датасету (923 эффекта): + +- `attr1 = 0`, `attr2 = 0`, `attr3 = 1`. + +### 2.2. Export API `Effect.dll` + +Экспортируются: + +- `CreateFxManager(int a1, int a2, int owner)`; +- `InitializeSettings()`. + +`CreateFxManager` создаёт manager-объект (`0xB8` байт), инициализирует через `sub_10003AE0`, возвращает интерфейсный указатель (`base + 4`). + +### 2.3. Интерфейс менеджера + +Рабочая vtable (`off_1001E478`): + +| Смещение | Функция | Назначение | +|---|---|---| +| +0x08 | `sub_10003D30` | Event dispatcher (`4/20/23/24/28`) | +| +0x10 | `sub_10004320` | Открыть/закэшировать FX resource | +| +0x14 | `sub_10004590` | Создать runtime instance | +| +0x18 | `sub_10004780` | Удалить instance | +| +0x1C | `sub_100047B0` | Установить time/interp mode | +| +0x20 | `sub_100047D0` | Установить scale | +| +0x24 | `sub_10004830` | Установить позицию | +| +0x28 | `sub_10004930` | Установить matrix transform | +| +0x2C | `sub_10004B00` | Restart/retime | +| +0x38 | `sub_10004BA0` | Duration modifier | +| +0x3C | `sub_10004BD0` | Start/Enable | +| +0x40 | `sub_10004C10` | Stop/Disable | +| +0x44 | `sub_10004C50` | Bind emitter/context | +| +0x48 | `sub_10004D50` | Сброс frame flags | + +`Terrain.dll` использует `QueryInterface(id=19)` для получения рабочего интерфейса. + +--- + +## 3. Бинарный формат FXID payload + +Все значения little-endian. + +### 3.1. Header (60 байт, `0x3C`) + +```c +struct FxHeader60 { + uint32_t cmd_count; // 0x00 + uint32_t time_mode; // 0x04 + float duration_sec; // 0x08 + float phase_jitter; // 0x0C + uint32_t flags; // 0x10 + uint32_t settings_id; // 0x14 + float rand_shift_x; // 0x18 + float rand_shift_y; // 0x1C + float rand_shift_z; // 0x20 + float pivot_x; // 0x24 + float pivot_y; // 0x28 + float pivot_z; // 0x2C + float scale_x; // 0x30 + float scale_y; // 0x34 + float scale_z; // 0x38 +}; +``` + +Командный поток начинается строго с `offset = 0x3C`. + +### 3.2. Header-поля (подтвержденная семантика) + +- `cmd_count`: число команд (engine итерирует ровно столько шагов). +- `time_mode`: базовый режим вычисления alpha/time (`sub_10005C60`). +- `duration_sec`: в runtime -> `duration_ms = duration_sec * 1000`. +- `phase_jitter`: используется при `flags & 0x1`. +- `flags`: runtime-gating/alpha/visibility (см. ниже). +- `settings_id`: в `sub_1000EC40` используется `settings_id & 0xFF`. +- `rand_shift_*`: используется при `flags & 0x8`. +- `pivot_*`: используется в ветках `sub_10007D10`. +- `scale_*`: копируется в runtime scale и влияет на матрицы. + +### 3.3. `flags` (битовая карта) + +| Бит | Маска | Наблюдаемое поведение | +|---|---:|---| +| 0 | `0x0001` | Random phase jitter (`phase_jitter`) | +| 3 | `0x0008` | Random positional shift (`rand_shift_*`) | +| 4 | `0x0010` | Visibility/occlusion ветки | +| 5 | `0x0020` | Triangular remap в `sub_10005C60` | +| 6 | `0x0040` | Инверсия начального active-state | +| 7 | `0x0080` | Day/night filter (ветка A) | +| 8 | `0x0100` | Day/night filter (ветка B, инверсия) | +| 9 | `0x0200` | Alpha *= normalized lifetime | +| 10 | `0x0400` | Установка manager bit1 (`+0xA0`) | +| 11 | `0x0800` | Изменение gating в `sub_10007D10` | +| 12 | `0x1000` | Установка manager-state bit `0x10` | + +Нерасшифрованные биты должны сохраняться 1:1. + +### 3.4. `time_mode` (`0..17`) + +Обозначения (`sub_10005C60`): + +- `t0 = instance.start_ms`, `t1 = instance.end_ms`; +- `tn = (now_ms - t0) / (t1 - t0)`; +- `prev = instance.cached_alpha` (`v4+52` в дизассембле). + +Режимы: + +- `0`: constant (`instance.alpha_const`, поле `v4+40`); +- `1`: `tn`; +- `2`: `fract(tn)`; +- `3`: `1 - tn`; +- `4`: external value из queue/world API (manager `+36`, id из `this+104[a2]`); +- `5`: `|param33.xyz| / |param17.vecA.xyz|`; +- `6`: `param33.x / param17.vecA.x`; +- `7`: `param33.y / param17.vecA.y`; +- `8`: `param33.z / param17.vecA.z`; +- `9`: `|param36.xyz| / |param17.vecB.xyz|`; +- `10`: `param36.x / param17.vecB.x`; +- `11`: `param36.y / param17.vecB.y`; +- `12`: `param36.z / param17.vecB.z`; +- `13`: `1 - external_resource_value`; +- `14`: `1 - queue_param(49)`; +- `15`: `max(norm(param33/vecA), norm(param36/vecB))`; +- `16`: external (`mode 4`) с нижним clamp к `prev` (`0` не зажимается); +- `17`: external (`mode 4`) с верхним clamp к `prev` (`1` не зажимается). + +Post-обработка после mode: + +- если `flags & 0x200`: `alpha *= tn`; +- если `flags & 0x20`: triangular remap (`alpha = (alpha < 0.5 ? alpha : 1-alpha) * 2`). + +--- + +## 4. Командный поток + +### 4.1. Общий формат команды + +Каждая команда: + +- `uint32 cmd_word`; +- далее body фиксированного размера по opcode. + +`cmd_word`: + +- `opcode = cmd_word & 0xFF`; +- `enabled = (cmd_word >> 8) & 1`; +- `bits 9..31` в датасете нулевые, но их надо сохранять 1:1. + +Выравнивания между командами нет. + +### 4.2. Размеры + +| Opcode | Размер записи | +|---:|---:| +| 1 | 224 | +| 2 | 148 | +| 3 | 200 | +| 4 | 204 | +| 5 | 112 | +| 6 | 4 | +| 7 | 208 | +| 8 | 248 | +| 9 | 208 | +| 10 | 208 | + +### 4.3. Opcode -> runtime-класс (vtable) + +| Opcode | `new(size)` | vtable | +|---:|---:|---| +| 1 | `0xF0` | `off_1001E78C` | +| 2 | `0xA0` | `off_1001F048` | +| 3 | `0xFC` | `off_1001E770` | +| 4 | `0x104` | `off_1001E754` | +| 5 | `0x54` | `off_1001E360` | +| 6 | `0x1C` | `off_1001E738` | +| 7 | `0x48` | `off_1001E228` | +| 8 | `0xAC` | `off_1001E71C` | +| 9 | `0x100` | `off_1001E700` | +| 10 | `0x48` | `off_1001E24C` | + +### 4.4. Общий вызовной контракт команды + +После создания команды (`sub_10007650`): + +1. `cmd->enabled = cmd_word.bit8`. +2. `cmd->Init(fx_queue, fx_instance)` (`vfunc +4`). +3. команда добавляется в список инстанса. + +В runtime cycle: + +- `vfunc +8`: update/compute (bool); +- `vfunc +12`: emission/render callback; +- `vfunc +20`: toggle active; +- `vfunc +16`/`+24`: служебные функции (зависят от opcode). + +--- + +## 5. Загрузка FXID (engine-accurate) + +`sub_10007650`: + +```c +void FxLoad(FxInstance* fx, uint8_t* payload) { + FxHeader60* h = (FxHeader60*)payload; + + fx->raw_header = h; + fx->mode = h->time_mode; + fx->end_ms = fx->start_ms + h->duration_sec * 1000.0f; + fx->scale = {h->scale_x, h->scale_y, h->scale_z}; + fx->active_default = ((h->flags & 0x40) == 0); + + uint8_t* ptr = payload + 0x3C; + for (uint32_t i = 0; i < h->cmd_count; ++i) { + uint32_t w = *(uint32_t*)ptr; + uint8_t op = (uint8_t)(w & 0xFF); + + Command* cmd = CreateByOpcode(op, ptr); // может вернуть null + if (cmd) { + cmd->enabled = (w >> 8) & 1; + + if (h->flags & 0x400) fx->manager_flags |= 0x0100; + if ((h->flags & 0x400) || cmd->enabled) fx->manager_flags |= 0x0010; + + cmd->Init(fx->queue, fx); + fx->commands.push_back(cmd); + } + + ptr += size_by_opcode(op); // без bounds checks в оригинале + } +} +``` + +Критичные edge-case оригинала: + +- bounds checks отсутствуют; +- при unknown opcode `ptr` не двигается (`advance = 0`); +- при `new == null` команда пропускается, но `ptr` двигается. + +Фактический `advance` в `sub_10007650` задан hardcoded в DWORD: + +- `op1:+56`, `op2:+37`, `op3:+50`, `op4:+51`, `op5:+28`, +- `op6:+1`, `op7:+52`, `op8:+62`, `op9:+52`, `op10:+52`, +- `default:+0`. + +--- + +## 6. Runtime lifecycle + +- `sub_10007470`: ctor instance. +- `sub_10003D30(case 28)`: per-frame update manager. +- `sub_10006170`: gate + alpha/time + command updates. +- `sub_10008120` / `sub_10007D10`: update/render branches. +- Start/Stop: `sub_10004BD0` / `sub_10004C10`. + +Event-codes `sub_10003D30`: + +- `4`: bootstrap/time init; +- `20`: range-removal + index repair; +- `23`: set manager bit0; +- `24`: clear manager bit0; +- `28`: main tick. + +--- + +## 7. Общий тип `ResourceRef64` + +Для opcode `2/3/4/5/7/8/9/10` присутствует ссылка вида: + +```c +struct ResourceRef64 { + char archive[32]; // null-terminated ASCII, case-insensitive compare + char name[32]; // null-terminated ASCII +}; +``` + +Поведение loader'а: + +- оба имени обязаны быть непустыми; +- кэширование по `(_strcmpi archive, _strcmpi name)`; +- загрузка/резолв через manager resource API. + +Наблюдение по данным: + +- для `opcode 2`: обычно `sounds.lib` + `*.wav`; +- для остальных: обычно `material.lib` + material name. + +--- + +## 8. Полная карта body по opcode (field-level) + +Смещения указаны от начала команды (включая `cmd_word`). + +### 8.1. Opcode 1 (`off_1001E78C`, size=224) + +Основные методы: + +- init: `sub_1000F4B0`; +- update: `sub_1000F6E0`; +- emit: `nullsub_2`; +- toggle: `sub_1000F490`. + +```c +struct FxCmd01 { + uint32_t word; // +0 + uint32_t mode; // +4 (enum, см. ниже) + float t_start; // +8 + float t_end; // +12 + + float p0_min[3]; // +16..24 + float p0_max[3]; // +28..36 + + float p1_min[3]; // +40..48 + float p1_max[3]; // +52..60 + + float q0_min[4]; // +64..76 + float q0_max[4]; // +80..92 + + float q0_rand_span[4]; // +96..108 (все 4 читаются в sub_1000F6E0) + + float scalar_min; // +112 + float scalar_max; // +116 + float scalar_rand_amp; // +120 + + float color_rgb[3]; // +124..132 (вызов manager+16) + + float opaque_tail6[6]; // +136..156 (сохранять 1:1; в датасете почти всегда 0) + + char opt_archive[32]; // +160..191 (редко, напр. "material.lib") + char opt_name[32]; // +192..223 (редко, напр. "light_w") +}; +``` + +Замечания по полям op1: + +- `+108` не резерв: участвует в random-выборке как 4-я компонента блока `+96..108`; +- `+136..156` не читается vtable-методами класса `off_1001E78C` в `Effect.dll` (init/update/toggle/accessor), но должно сохраняться 1:1; +- редкий кейс с ненулевыми `+136..156` и строками `+160/+192` зафиксирован в `effects.rlb:r_lightray_w`. + +`mode` (`+4`) -> параметры вызова manager (`sub_1000F4B0`): + +- `1 -> create_kind=1, flags=0x80000000`; +- `2/5 -> create_kind=1, flags=0x00000000`; +- `3 -> create_kind=3, flags=0x00000000`; +- `4 -> create_kind=4, flags=0x00000000`; +- `6 -> create_kind=1, flags=0xA0000000`; +- `7 -> create_kind=1, flags=0x20000000`. + +### 8.2. Opcode 2 (`off_1001F048`, size=148) + +Основные методы: + +- init: `sub_10012D10`; +- update: `sub_10012EB0`; +- emit: `nullsub_2`; +- toggle: `sub_10013170`. + +```c +struct FxCmd02 { + uint32_t word; // +0 + uint32_t mode; // +4 (0..3; влияет на sub_100065A0 mapping) + float t_start; // +8 + float t_end; // +12 + + float a_min[3]; // +16..24 + float a_max[3]; // +28..36 + + float b_min[3]; // +40..48 + float b_max[3]; // +52..60 + + float c0_base; // +64 + float c1_base; // +68 + float c2_base; // +72 + float c2_max; // +76 + + uint32_t param_910; // +80 (передаётся в manager cmd=910) + + ResourceRef64 ref; // +84..147 (обычно sounds.lib + wav) +}; +``` + +`mode` -> внутренний map в `sub_100065A0`: + +- `0 -> 0`, `1 -> 512`, `2 -> 2`, `3 -> 514`. + +### 8.3. Opcode 3 (`off_1001E770`, size=200) + +Методы: + +- init: `sub_100103B0`; +- update: `sub_100105F0`; +- emit: `sub_100106C0`. + +```c +struct FxCmd03 { + uint32_t word; // +0 + uint32_t mode; // +4 + + float alpha_source; // +8 (>=0: norm time, <0: global time) + float alpha_pow_a; // +12 + float alpha_pow_b; // +16 + + float out_min; // +20 + float out_max; // +24 + float out_pow; // +28 + + float active_t0; // +32 + float active_t1; // +36 + + float v0_min[3]; // +40..48 + float v0_max[3]; // +52..60 + + float pow0[3]; // +64..72 + + float v1_min[3]; // +76..84 + float v1_max[3]; // +88..96 + + float v2_min[3]; // +100..108 + float v2_max[3]; // +112..120 + + float pow1[3]; // +124..132 + + ResourceRef64 ref; // +136..199 +}; +``` + +### 8.4. Opcode 4 (`off_1001E754`, size=204) + +Layout как opcode 3 + последний коэффициент: + +```c +struct FxCmd04 { + FxCmd03 base; // +0..199 + float dist_norm_inv_base; // +200 (используется в sub_100108C0/100109B0) +}; +``` + +`sub_100108C0`: `obj->inv = 1.0 / raw[200]`. + +### 8.5. Opcode 5 (`off_1001E360`, size=112) + +Методы: + +- init: `sub_100028A0`; +- update: `sub_10002A20`; +- emit: `sub_10002BE0`; +- context update: `sub_10003070`. + +```c +struct FxCmd05 { + uint32_t word; // +0 + uint32_t mode; // +4 (в данных обычно 1) + uint32_t unused_08; // +8 (в текущем коде opcode5 не читается) + uint32_t unused_0C; // +12 (в текущем коде opcode5 не читается) + + float active_t0; // +16 + uint32_t max_segments; // +20 + float active_t1_min; // +24 + float active_t1_max; // +28 + + float step_norm; // +32 + float segment_len; // +36 + float alpha_source; // +40 (>=0 norm, <0 random) + float alpha_pow; // +44 + + ResourceRef64 ref; // +48..111 +}; +``` + +### 8.6. Opcode 6 (`off_1001E738`, size=4) + +Только `cmd_word`: + +```c +struct FxCmd06 { + uint32_t word; // +0 +}; +``` + +`init/update/emit` фактически no-op (`sub_100030B0` возвращает `0`). + +### 8.7. Opcode 7 (`off_1001E228`, size=208) + +Методы: + +- init: `sub_10001720`; +- update: `sub_10001230`; +- emit: `sub_10001300`; +- element accessor: `sub_10002780`. + +```c +struct FxCmd07 { + uint32_t word; // +0 + uint32_t mode; // +4 + + float eval_min; // +8 + float eval_max; // +12 + float eval_pow; // +16 + + float active_t0; // +20 + float active_t1; // +24 + + float phase_span; // +28 + float phase_rate; // +32 + + uint32_t count_a; // +36 + uint32_t count_b; // +40 + + float set0_min[3]; // +44..52 + float set0_max[3]; // +56..64 + float set0_rand[3]; // +68..76 + float set0_pow[3]; // +80..88 + + float set1_min[3]; // +92..100 + float set1_max[3]; // +104..112 + float set1_rand[3]; // +116..124 + float set1_pow[3]; // +128..136 + + float gravity_or_drag_k; // +140 + + ResourceRef64 ref; // +144..207 +}; +``` + +### 8.8. Opcode 8 (`off_1001E71C`, size=248) + +Методы: + +- init: `sub_10011230`; +- update: `sub_100115C0`; +- emit: `sub_10012030`. + +```c +struct FxCmd08 { + uint32_t word; // +0 + uint32_t mode; // +4 + + float eval_t0; // +8 + float eval_t1; // +12 + + float gate_t0; // +16 + float gate_t1; // +20 + + float period_min; // +24 + float period_max; // +28 + float phase_pow; // +32 + + uint32_t slots; // +36 + + float set0_min[3]; // +40..48 + float set0_max[3]; // +52..60 + float set0_rand[3]; // +64..72 + + float set1_min[3]; // +76..84 + float set1_max[3]; // +88..96 + float set1_rand[3]; // +100..108 + + float set2_rand[3]; // +112..120 + float set2_pow[3]; // +124..132 + + float rmax_set0[3]; // +136..144 (bound/radius calc) + float rmax_set1[3]; // +148..156 (bound/radius calc) + float rmax_set2[3]; // +160..168 (bound/radius calc) + + float render_pow[3]; // +172..180 + + ResourceRef64 ref; // +184..247 +}; +``` + +### 8.9. Opcode 9 (`off_1001E700`, size=208) + +Layout как opcode 3 с двумя final-полями: + +```c +struct FxCmd09 { + FxCmd03 base; // +0..199 + uint32_t render_kind; // +200 (0/1/2 -> 3/5/6 in sub_100138C0) + uint32_t render_flag; // +204 (0 -> добавляет bit 0x08000000) +}; +``` + +Методы: + +- init/update как у opcode 3 (`sub_100103B0`, `sub_100105F0`); +- emit: `sub_100138C0` -> формирует код рендера и вызывает `sub_100106C0`. + +### 8.10. Opcode 10 (`off_1001E24C`, size=208) + +Body-layout совпадает с opcode 7 (`FxCmd07`), но другой runtime класс. + +- init: `sub_10001A40`; +- update: `sub_10001230`; +- emit: `sub_10001300`; +- element accessor: `sub_10002830`. + +Наблюдение по данным: + +- `mode` (`+4`) встречается как `16` или `32`. + +--- + +## 9. Runtime-специфика по opcode (важные отличия) + +### 9.1. Opcode 1 + +- создаёт handle через manager (`vfunc +48`); +- задаёт флаги handle (`vfunc +52`); +- в update пушит: + - позиционный вектор 1 (`vfunc +32`), + - позиционный вектор 2 (`vfunc +36`), + - 4-компонентный параметр (`vfunc +12`), + - scalar+rgb (`vfunc +16`). + +### 9.2. Opcode 2 + +- `ResourceRef64` резолвится через `sub_100065A0` (режим-зависимая загрузка, в данных обычно `sounds.lib`/`wav`); +- использует manager-команду id `910`. + +### 9.3. Opcode 3/4/9 + +- общий core-emitter в `sub_100106C0`; +- opcode 4 добавляет нормализацию по `raw+200`; +- opcode 9 добавляет переключение render-кода (`raw+200/+204`). + +### 9.4. Opcode 5 + +- держит массив внутренних сегментов (`332` байта/элемент, ctor `sub_100099F0`); +- context-matrix приходит через `vfunc +24` (`sub_10003070`). + +### 9.5. Opcode 7/10 + +- общий update/render (`sub_10001230`, `sub_10001300`); +- разные внутренние element-форматы: + - opcode 7: `204` байта/элемент (`sub_100092D0`), + - opcode 10: `492` байта/элемент (`sub_1000BB40`). + +### 9.6. Opcode 8 + +- самый тяжёлый спавнер, хранит ring/slot-структуры; +- emit фаза (`sub_10012030`) использует `mode`, `render_pow`, per-slot transforms. + +--- + +## 10. Спецификация инструментов + +### 10.1. Reader (strict) + +Алгоритм: + +1. `len(payload) >= 60`; +2. читаем `cmd_count`; +3. `ptr = 0x3C`; +4. цикл `cmd_count`: + - `ptr + 4 <= len`; + - `opcode in 1..10`; + - `ptr + size(opcode) <= len`; + - `ptr += size(opcode)`; +5. strict-tail: `ptr == len(payload)`. + +### 10.2. Reader (engine-compatible) + +Legacy-режим (опасный, только при необходимости byte-совместимости): + +- без bounds-check; +- tolerant к unknown opcode как в оригинале. + +### 10.3. Writer (canonical) + +1. записать `FxHeader60`; +2. `cmd_count = commands.len()`; +3. команды сериализуются как `cmd_word + fixed-body`; +4. размер payload: `0x3C + sum(size(op_i))`; +5. без хвостовых байт. + +### 10.4. Editor (lossless) + +Правила: + +- все поля little-endian; +- не менять fixed size команды; +- не добавлять padding; +- сохранять неизвестные биты (`cmd_word`, `header.flags`) copy-through; +- для частично-известных полей поддерживать режим `opaque`. + +### 10.5. IR/JSON (рекомендуемая форма) + +```json +{ + "header": { + "time_mode": 1, + "duration_sec": 2.5, + "phase_jitter": 0.2, + "flags": 22, + "settings_id": 785, + "rand_shift": [0.0, 0.0, 0.0], + "pivot": [0.0, 0.0, 0.0], + "scale": [1.0, 1.0, 1.0] + }, + "commands": [ + { + "opcode": 8, + "word_raw": 264, + "enabled": 1, + "fields": { + "mode": 1065353216, + "eval_t0": 0.0, + "eval_t1": 1.0, + "resource": {"archive": "material.lib", "name": "fire_smoke"} + }, + "opaque_extra_hex": "..." + } + ] +} +``` + +--- + +## 11. Проверка на реальных данных + +`testdata/nres`: + +- FXID payload: `923`; +- валидация parser'а: `923/923 valid`. + +Распределение opcode: + +- `1: 618` +- `2: 517` +- `3: 1545` +- `4: 202` +- `5: 31` +- `6: 0` (в датасете не встречен, но поддержан) +- `7: 1161` +- `8: 237` +- `9: 266` +- `10: 160` + +Подтверждённые `ResourceRef64` оффсеты: + +- op2 `+84`, op3/4/9 `+136`, op5 `+48`, op7/10 `+144`, op8 `+184`. + +Для op1 найден редкий расширенный хвост (`+160/+192`) в `effects.rlb:r_lightray_w`: + +- `material.lib` / `light_w`. + +--- + +## 12. Практический чек-лист 1:1 + +Для runtime-порта: + +- реализовать `FxHeader60` и parser `sub_10007650`; +- реализовать opcode-классы с методами как в vtable; +- учитывать start/stop/restart контракт manager API; +- воспроизвести `sub_10005C60` + post-flags (`0x20`, `0x200`); +- воспроизвести event loop `sub_10003D30(case 28)`. + +Для toolchain: + +- strict validator по разделу 10.1; +- canonical writer по разделу 10.3; +- field-aware editor + opaque fallback для неизвестных зон. + +--- + +## 13. Что считать «полной» совместимостью + +Практический критерий завершения: + +1. Парсер и writer дают byte-identical round-trip для всех 923 FXID. +2. Runtime-порт выдаёт совпадающие state transitions на одинаковом `dt/seed` (по ключевым полям instance + command state). +3. Все opcode `1..10` поддержаны (включая `6`, даже если отсутствует в текущем датасете). +4. `ResourceRef64` и mode-ветки (`op1`, `op2`, `op9`) совпадают с оригиналом. + +Эта страница покрывает весь наблюдаемый контракт формата/рантайма и полную карту body-полей по всем opcode. + +--- + +## 14. Что осталось до «абсолютных 100%» + +Для практического 1:1 (парсер/writer/runtime на известном контенте) покрытие уже достаточно. +Для «абсолютных 100%» на любых входах и во всех краевых режимах остаются 3 пункта: + +1. FP-детерминизм: оригинал опирается на x87-style вычисления; SSE/fast-math могут давать расхождения в alpha/таймингах. +2. RNG parity: используется `sub_10002220` (16-bit генератор) и глобальные seed-состояния; для bit-exact воспроизведения нужны контрольные трассы оригинала. +3. Редкие ветки данных: в текущем датасете нет opcode `6`, и почти не встречаются хвосты op1 (`+136..223`); для исчерпывающей валидации нужны дополнительные FXID-образцы. + +Что нужно собрать, чтобы закрыть это полностью: + +- frame-by-frame dump из оригинального runtime (alpha, manager flags, per-command state); +- контрольные прогоны при фиксированном `dt` и seed; +- минимум по одному ресурсу на каждую редкую ветку (`op6`, op1-tail с ненулевыми `+136..223`). |