path: root/docs/specs/fxid.md

# 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`).