aboutsummaryrefslogtreecommitdiff
path: root/docs/specs
diff options
context:
space:
mode:
Diffstat (limited to 'docs/specs')
-rw-r--r--docs/specs/fxid.md936
1 files changed, 654 insertions, 282 deletions
diff --git a/docs/specs/fxid.md b/docs/specs/fxid.md
index 65bf7f1..957f95b 100644
--- a/docs/specs/fxid.md
+++ b/docs/specs/fxid.md
@@ -1,382 +1,730 @@
# FXID
-Документ описывает формат ресурса эффекта `FXID`, контракт runtime в `Effect.dll` и практические правила для инструментов чтения/конвертации/редактирования.
+Документ фиксирует спецификацию ресурса эффекта `FXID` на уровне, достаточном для:
-Цель: дать достаточную high-level спецификацию для:
-
-- 1:1 загрузчика/рантайма эффекта;
-- валидатора payload;
-- бинарно-совместимого редактора;
-- конвертера в промежуточный формат и обратно.
+- 1:1 загрузки и исполнения в совместимом runtime;
+- построения валидатора payload;
+- создания lossless-конвертера (`binary -> IR -> binary`);
+- создания редактора с безопасным редактированием полей.
Связанный контейнер: [NRes / RsLi](nres.md).
---
-## 1. Источники восстановления
+## 1. Источники и статус восстановления
-Спецификация собрана по:
+Спецификация восстановлена по:
- `tmp/disassembler1/Effect.dll.c`;
- `tmp/disassembler2/Effect.dll.asm`;
- интеграционным вызовам из `tmp/disassembler1/Terrain.dll.c`;
- проверке реальных архивов `testdata/nres`.
-Ключевые точки:
+Ключевые функции:
- parser FXID: `Effect.dll!sub_10007650`;
-- core update: `Effect.dll!sub_10008120`, `sub_10006170`, `sub_10007D10`;
-- export API: `CreateFxManager`, `InitializeSettings`.
+- 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. Место формата в движке
+## 2. Контейнер и runtime API
-### 2.1. Контейнер NRes
+## 2.1. NRes entry
-Эффект хранится как запись NRes с типом:
+FXID хранится как NRes-entry:
- `type_id = 0x44495846` (`"FXID"`).
-Для всех 923 FXID-entries в `testdata/nres` подтверждено:
+Наблюдение по датасету (923 эффекта):
-- `attr1 = 0`;
-- `attr2 = 0`;
-- `attr3 = 1`.
+- `attr1 = 0`, `attr2 = 0`, `attr3 = 1`.
-### 2.2. Runtime-модуль
+## 2.2. Export API `Effect.dll`
-`Effect.dll` экспортирует 2 функции:
+Экспортируются:
- `CreateFxManager(int a1, int a2, int owner)`;
- `InitializeSettings()`.
-`CreateFxManager` выделяет объект (`0xB8` байт), инициализирует его через `sub_10003AE0`, возвращает **интерфейсный указатель** (смещение `+4` от базового объекта).
+`CreateFxManager` создаёт manager-объект (`0xB8` байт), инициализирует через `sub_10003AE0`, возвращает интерфейсный указатель (`base + 4`).
-### 2.3. COM-подобный интерфейс
+## 2.3. Интерфейс менеджера
-Внешний код (например, `Terrain.dll`) получает рабочий интерфейс через `QueryInterface(id=19)` и далее вызывает методы vtable `off_1001E478`.
+Рабочая vtable (`off_1001E478`):
-Ключевые методы интерфейса менеджера (по vtable):
-
-| Vtable offset | Функция | Назначение (high-level) |
+| Смещение | Функция | Назначение |
|---|---|---|
-| +0x10 | `sub_10004320` | Открыть/закэшировать ресурс эффекта (`archive + name`) |
-| +0x14 | `sub_10004590` | Создать runtime-инстанс эффекта по шаблону |
-| +0x18 | `sub_10004780` | Удалить инстанс по id |
-| +0x1C | `sub_100047B0` | Установить режим интерполяции/времени |
+| +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` | Установить матрицу transform |
-| +0x2C | `sub_10004B00` | Перезапуск с mode |
-| +0x38 | `sub_10004BA0` | Модификатор длительности |
+| +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` | Привязать emitter/context |
-| +0x48 | `sub_10004D50` | Сброс frame-флагов |
-| +0x08 | `sub_10003D30` | Системные event-коды (tick/reset/remove-range) |
+| +0x44 | `sub_10004C50` | Bind emitter/context |
+| +0x48 | `sub_10004D50` | Сброс frame flags |
-Этого контракта достаточно, чтобы корректно встроить FXID-рантайм в движок.
+`Terrain.dll` использует `QueryInterface(id=19)` для получения рабочего интерфейса.
---
-## 3. Бинарный формат payload FXID
+## 3. Бинарный формат FXID payload
-Все числа little-endian.
+Все значения little-endian.
## 3.1. Header (60 байт, `0x3C`)
```c
struct FxHeader60 {
- uint32_t cmd_count; // 0x00: число команд
- uint32_t time_mode; // 0x04: базовый режим вычисления alpha/time
- float duration_sec; // 0x08: длительность эффекта в секундах
- float phase_jitter; // 0x0C: амплитуда рандом-сдвига alpha (если flags bit0)
- uint32_t flags; // 0x10: флаги runtime (см. таблицу ниже)
- uint32_t settings_id; // 0x14: id категории/настройки (используется low8)
- float rand_shift_x; // 0x18: рандомный сдвиг (если flags bit3)
- float rand_shift_y; // 0x1C
- float rand_shift_z; // 0x20
- float pivot_x; // 0x24: опорная точка/anchor
- float pivot_y; // 0x28
- float pivot_z; // 0x2C
- float scale_x; // 0x30: базовый scale
- float scale_y; // 0x34
- float scale_z; // 0x38
+ 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 итерируется ровно `cmd_count` раз;
- - дополнительных ограничений в оригинале нет.
-- `time_mode`:
- - начальный runtime-mode (`effect+0x14`), участвует в `sub_10005C60`.
-- `duration_sec`:
- - переводится в миллисекунды как `duration_ms = duration_sec * 1000.0`.
-- `phase_jitter`:
- - при `flags & 0x1` к вычисленному alpha добавляется рандом в диапазоне `[-phase_jitter/2, +phase_jitter/2]`.
-- `settings_id`:
- - `sub_1000EC40` использует только `settings_id & 0xFF` как индекс таблицы настроек.
-- `rand_shift_*`:
- - при `flags & 0x8` добавляется рандомный сдвиг к позиции эффекта.
-- `pivot_*`:
- - используется как опорная точка в ветках проверки видимости/окклюзии (`sub_10007D10`).
-- `scale_*`:
- - копируется в runtime (`this+56..64`) и участвует в построении матрицы в `sub_10007C90`.
-
-## 3.3. `flags` (`header+0x10`) — подтвержденные биты
-
-| Бит | Маска | Поведение |
+## 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` | Участвует в ветках видимости/окклюзии в `sub_10006170`/`sub_10007D10` |
-| 5 | `0x0020` | Треугольная ремап-функция alpha в `sub_10005C60` |
-| 6 | `0x0040` | Инвертирует начальное активное состояние (`this+324 = !(flags&0x40)`) |
-| 7 | `0x0080` | Условная фильтрация по manager-флагу day/night |
-| 8 | `0x0100` | Инверсная day/night фильтрация |
-| 9 | `0x0200` | Домножение alpha на нормализованное время жизни |
-| 10 | `0x0400` | Включает manager-глобальный флаг (`manager+0xA0` bit1) |
-| 11 | `0x0800` | Меняет поведение ветки `sub_10007D10` (gating для checks) |
-| 12 | `0x1000` | Проставляет manager-state bit0x10 в `sub_10006170` |
-
-Остальные биты в движке напрямую не расшифрованы на уровне high-level, но должны сохраняться 1:1.
-
-## 3.4. `time_mode` (`header+0x04`) — режимы `sub_10005C60`
-
-Поддерживаются коды `0..17`.
-
-| mode | Логика |
-|---:|---|
-| 0 | Константа (значение из runtime-поля) |
-| 1 | Линейно: `(t - t0) / (t1 - t0)` |
-| 2 | Цикл `frac((t - t0)/(t1 - t0))` |
-| 3 | Обратная линейная: `1 - (t - t0)/(t1 - t0)` |
-| 4 | Значение из внешнего queue/world-запроса |
-| 5..8 | Нормированные отношения компонент вектора (camera/world path) |
-| 9..12 | Альтернативный набор нормированных отношений |
-| 13 | `1 - value` из queue-запроса по объекту |
-| 14 | `1 - value` из параметра queue id=49 |
-| 15 | max из двух нормированных длин |
-| 16 | Кламп "не убывать" относительно предыдущего значения |
-| 17 | Кламп "не возрастать" относительно предыдущего значения |
-
-После базового mode-преобразования применяются post-флаги `0x200` и `0x20`.
+| 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. Формат записи команды
+## 4.1. Общий формат команды
+
+Каждая команда:
-Каждая команда начинается с `uint32 cmd_word`.
+- `uint32 cmd_word`;
+- далее body фиксированного размера по opcode.
-Биты:
+`cmd_word`:
- `opcode = cmd_word & 0xFF`;
- `enabled = (cmd_word >> 8) & 1`;
-- в реальных данных `bits 9..31 == 0` (но редактор должен сохранять весь word как есть).
-
-Никакого межкомандного выравнивания нет: следующая команда начинается сразу после `size(opcode)`.
+- `bits 9..31` в датасете нулевые, но их надо сохранять 1:1.
-## 4.2. Размеры записей по opcode
+Выравнивания между командами нет.
-| Opcode | Размер записи (байт) | Размер тела после `cmd_word` |
-|---:|---:|---:|
-| 1 | 224 | 220 |
-| 2 | 148 | 144 |
-| 3 | 200 | 196 |
-| 4 | 204 | 200 |
-| 5 | 112 | 108 |
-| 6 | 4 | 0 |
-| 7 | 208 | 204 |
-| 8 | 248 | 244 |
-| 9 | 208 | 204 |
-| 10 | 208 | 204 |
+## 4.2. Размеры
-## 4.3. Opcode -> runtime-класс
+| Opcode | Размер записи |
+|---:|---:|
+| 1 | 224 |
+| 2 | 148 |
+| 3 | 200 |
+| 4 | 204 |
+| 5 | 112 |
+| 6 | 4 |
+| 7 | 208 |
+| 8 | 248 |
+| 9 | 208 |
+| 10 | 208 |
-В `sub_10007650` для opcode создаются объекты:
+## 4.3. Opcode -> runtime-класс (vtable)
-| Opcode | `operator new` | 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` |
+| 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` |
-Важно: payload команды хранится как сырой указатель и разбирается runtime-методами класса.
+## 4.4. Общий вызовной контракт команды
-## 4.4. Внутренний вызовной контракт команд
+После создания команды (`sub_10007650`):
-После создания каждой команды менеджер:
+1. `cmd->enabled = cmd_word.bit8`.
+2. `cmd->Init(fx_queue, fx_instance)` (`vfunc +4`).
+3. команда добавляется в список инстанса.
-1. Проставляет `enabled` из `cmd_word.bit8` в поле `obj+4`.
-2. Вызывает инициализацию команды (`vfunc +4`) с аргументами `(queue, manager)`.
-3. Добавляет команду в массив команд эффекта.
+В runtime cycle:
-В update-cycle менеджер вызывает:
-
-- `vfunc +8`: вычисление/обновление команды (bool);
-- `vfunc +12`: callback при render/emission;
-- `vfunc +20`: toggle активности;
-- `vfunc +24`: обновление transform-context (для части opcode no-op).
+- `vfunc +8`: update/compute (bool);
+- `vfunc +12`: emission/render callback;
+- `vfunc +20`: toggle active;
+- `vfunc +16`/`+24`: служебные функции (зависят от opcode).
---
-## 5. Алгоритм загрузки FXID (engine-accurate)
+## 5. Загрузка FXID (engine-accurate)
-Псевдокод `sub_10007650`:
+`sub_10007650`:
```c
void FxLoad(FxInstance* fx, uint8_t* payload) {
FxHeader60* h = (FxHeader60*)payload;
- fx->raw_header_ptr = h;
+ fx->raw_header = h;
fx->mode = h->time_mode;
- fx->end_ms = h->duration_sec * 1000.0f + fx->start_ms;
- fx->scale = { h->scale_x, h->scale_y, h->scale_z };
+ 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++) {
+ 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 = CreateCommandByOpcode(op, ptr); // может вернуть null
-
- if (cmd != null) {
+ Command* cmd = CreateByOpcode(op, ptr); // может вернуть null
+ if (cmd) {
cmd->enabled = (w >> 8) & 1;
- if (h->flags & 0x400)
- fx->manager_flags |= 0x0100; // внутренний bit
-
- if ((h->flags & 0x400) || cmd->enabled)
- fx->manager_flags |= 0x0010;
+ if (h->flags & 0x400) fx->manager_flags |= 0x0100;
+ if ((h->flags & 0x400) || cmd->enabled) fx->manager_flags |= 0x0010;
- cmd->Attach(fx->queue, fx);
+ cmd->Init(fx->queue, fx);
fx->commands.push_back(cmd);
}
- ptr += size_by_opcode(op); // в оригинале без checks
+ ptr += size_by_opcode(op); // без bounds checks в оригинале
}
}
```
-Поведение оригинала, важное для 1:1:
+Критичные edge-case оригинала:
+
+- bounds checks отсутствуют;
+- при unknown opcode `ptr` не двигается (`advance = 0`);
+- при `new == null` команда пропускается, но `ptr` двигается.
-- проверок границ буфера нет;
-- при `unknown opcode` указатель `ptr` не двигается (счётчик цикла движется);
-- при `new == null` команда пропускается, но `ptr` двигается на размер opcode.
+Фактический `advance` в `sub_10007650` задан hardcoded в DWORD:
-Для toolchain рекомендуется **строгий** и **безопасный** парсер (см. раздел 7).
+- `op1:+56`, `op2:+37`, `op3:+50`, `op4:+51`, `op5:+28`,
+- `op6:+1`, `op7:+52`, `op8:+62`, `op9:+52`, `op10:+52`,
+- `default:+0`.
---
-## 6. Runtime-жизненный цикл эффекта
+## 6. Runtime lifecycle
-## 6.1. Инициализация
+- `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`.
-- `sub_10007470`: конструктор instance;
-- инициализируются матрицы/scale/флаги;
-- начальный `mode` берётся из header.
+Event-codes `sub_10003D30`:
-## 6.2. Tick и обновление
+- `4`: bootstrap/time init;
+- `20`: range-removal + index repair;
+- `23`: set manager bit0;
+- `24`: clear manager bit0;
+- `28`: main tick.
+
+---
-Основной тик идёт через `sub_10003D30(case 28)`:
+## 7. Общий тип `ResourceRef64`
-1. обновление времени manager;
-2. обход активных FX instances;
-3. для каждого инстанса `sub_10006170`:
- - gating по `flags`/queue-state;
- - вычисление alpha через `sub_10005C60`;
- - вызов `sub_10008120` (update/bounds/command-pass);
- - при необходимости `sub_10007D10` (эмиссия/рендерный callback).
+Для opcode `2/3/4/5/7/8/9/10` присутствует ссылка вида:
-## 6.3. Start/Stop/Restart API
+```c
+struct ResourceRef64 {
+ char archive[32]; // null-terminated ASCII, case-insensitive compare
+ char name[32]; // null-terminated ASCII
+};
+```
-- Start: `sub_10004BD0` -> `sub_10007A30(..., 1, now)`;
-- Stop: `sub_10004C10` -> `sub_10007A30(..., 0, now)`;
-- Restart/retime: `sub_10004B00`, `sub_10004BA0`.
+Поведение loader'а:
-## 6.4. Manager event-codes (`sub_10003D30`)
+- оба имени обязаны быть непустыми;
+- кэширование по `(_strcmpi archive, _strcmpi name)`;
+- загрузка/резолв через manager resource API.
-Обработанные коды:
+Наблюдение по данным:
-- `4`: bootstrap + установка текущего времени;
-- `20`: удаление диапазона объектов в queue и корректировка индексов;
-- `23`: выставить manager-flag bit0;
-- `24`: сбросить manager-flag bit0;
-- `28`: основной per-frame update.
+- для `opcode 2`: обычно `sounds.lib` + `*.wav`;
+- для остальных: обычно `material.lib` + material name.
---
-## 7. Спецификация для инструментов
+## 8. Полная карта body по opcode (field-level)
-## 7.1. Reader (strict)
+Смещения указаны от начала команды (включая `cmd_word`).
-Рекомендуемый строгий парсер:
+## 8.1. Opcode 1 (`off_1001E78C`, size=224)
-1. проверить `len(payload) >= 60`;
-2. прочитать `cmd_count`;
-3. `ptr = 0x3C`;
-4. для каждой команды:
- - требовать `ptr + 4 <= len`;
- - прочитать `opcode`;
- - `opcode` должен быть в `1..10`;
- - `ptr + size(opcode) <= len`;
- - `ptr += size(opcode)`;
-5. в strict-режиме требовать `ptr == len(payload)`.
+Основные методы:
-Такой алгоритм совпадает с валидатором `tools/msh_doc_validator.py`.
+- init: `sub_1000F4B0`;
+- update: `sub_1000F6E0`;
+- emit: `nullsub_2`;
+- toggle: `sub_1000F490`.
-## 7.2. Reader (engine-compatible)
+```c
+struct FxCmd01 {
+ uint32_t word; // +0
+ uint32_t mode; // +4 (enum, см. ниже)
+ float t_start; // +8
+ float t_end; // +12
-Для byte-level совместимости с оригиналом можно поддержать legacy-режим:
+ float p0_min[3]; // +16..24
+ float p0_max[3]; // +28..36
-- без bounds-check (как `Effect.dll`);
-- с toleration на `unknown opcode` (но это потенциально unsafe).
+ float p1_min[3]; // +40..48
+ float p1_max[3]; // +52..60
-## 7.3. Editor (без потери совместимости)
+ float q0_min[4]; // +64..76
+ float q0_max[4]; // +80..92
-Безопасные операции:
+ float q0_rand_span[4]; // +96..108 (все 4 читаются в sub_1000F6E0)
-- менять `header`-поля (mode, duration, flags, scale, pivot);
-- менять `enabled` через `cmd_word.bit8`;
-- удалять/вставлять команды с корректным пересчётом `cmd_count` и сдвигом stream;
-- сохранять command-body как opaque bytes, если нет полного field-level декодера.
+ 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`).
-- всегда little-endian;
-- не менять размеры записей opcode;
-- не вставлять padding между командами;
-- для неизвестных битов `cmd_word` и `header.flags` использовать copy-through.
+## 8.7. Opcode 7 (`off_1001E228`, size=208)
-## 7.4. Writer (canonical)
+Методы:
-Каноническая сборка payload:
+- 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 = len(commands)`;
-3. для каждой команды записать `cmd_word` + body фиксированного размера для opcode;
-4. итоговый размер должен быть `0x3C + sum(size(opcode_i))`;
-5. без хвоста.
+2. `cmd_count = commands.len()`;
+3. команды сериализуются как `cmd_word + fixed-body`;
+4. размер payload: `0x3C + sum(size(op_i))`;
+5. без хвостовых байт.
+
+## 10.4. Editor (lossless)
+
+Правила:
-## 7.5. Конвертация в промежуточный JSON
+- все поля little-endian;
+- не менять fixed size команды;
+- не добавлять padding;
+- сохранять неизвестные биты (`cmd_word`, `header.flags`) copy-through;
+- для частично-известных полей поддерживать режим `opaque`.
-Рекомендуемая структура для round-trip:
+## 10.5. IR/JSON (рекомендуемая форма)
```json
{
@@ -392,71 +740,95 @@ void FxLoad(FxInstance* fx, uint8_t* payload) {
},
"commands": [
{
- "opcode": 3,
+ "opcode": 8,
+ "word_raw": 264,
"enabled": 1,
- "word_raw": 259,
- "body_hex": "..."
+ "fields": {
+ "mode": 1065353216,
+ "eval_t0": 0.0,
+ "eval_t1": 1.0,
+ "resource": {"archive": "material.lib", "name": "fire_smoke"}
+ },
+ "opaque_extra_hex": "..."
}
]
}
```
-`body_hex` хранит opaque payload без потери данных.
+---
+
+## 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`.
---
-## 8. Проверка на реальных данных
+## 12. Практический чек-лист 1:1
-`testdata/nres` (через `tools/msh_doc_validator.py`) :
+Для runtime-порта:
-- FXID effects: `923/923 valid`.
+- реализовать `FxHeader60` и parser `sub_10007650`;
+- реализовать opcode-классы с методами как в vtable;
+- учитывать start/stop/restart контракт manager API;
+- воспроизвести `sub_10005C60` + post-flags (`0x20`, `0x200`);
+- воспроизвести event loop `sub_10003D30(case 28)`.
-Дополнительно по этим 923 payload:
+Для toolchain:
-- `cmd_count`: min `0`, max `81`, avg `5.13`;
-- `duration_sec`: min `0.0`, max `60.0`, avg `2.46`;
-- `opcode` распределение:
- - `1: 618`
- - `2: 517`
- - `3: 1545`
- - `4: 202`
- - `5: 31`
- - `7: 1161`
- - `8: 237`
- - `9: 266`
- - `10: 160`
- - `6`: не встречен, но поддержан parser.
-- `cmd_word`:
- - `bits 9..31` не использованы в датасете;
- - `bit8` встречается для части opcode (особенно `3`, `7`, `9`).
+- strict validator по разделу 10.1;
+- canonical writer по разделу 10.3;
+- field-aware editor + opaque fallback для неизвестных зон.
---
-## 9. Известные пробелы (не блокируют 1:1 container/runtime)
+## 13. Что считать «полной» совместимостью
-1. Полная человеко-читаемая семантика **внутренних полей command body** для каждого opcode не завершена.
-2. Для части битов `header.flags` есть только functional-наблюдение без финального gameplay-имени.
-3. Высокие биты `settings_id` используются как есть (runtime читает low8); их предметное имя не зафиксировано.
+Практический критерий завершения:
-Это не мешает:
+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`) совпадают с оригиналом.
-- корректно читать/валидировать/пересобирать FXID;
-- делать lossless редактирование;
-- воспроизводить lifecycle менеджера и update-loop 1:1 на уровне контракта.
+Эта страница покрывает весь наблюдаемый контракт формата/рантайма и полную карту body-полей по всем opcode.
---
-## 10. Минимальный чек-лист реализации
+## 14. Что осталось до «абсолютных 100%»
-Для 1:1-порта движка:
+Для практического 1:1 (парсер/writer/runtime на известном контенте) покрытие уже достаточно.
+Для «абсолютных 100%» на любых входах и во всех краевых режимах остаются 3 пункта:
-- реализовать `FxHeader60` и stream parser по размерам opcode;
-- реализовать менеджер API (раздел 2.3);
-- реализовать tick-path `03D30(case 28)` -> `06170` -> `08120`/`07D10`;
-- учитывать флаги `0x40`, `0x400`, `0x800`, `0x1000`, `0x80/0x100`, `0x20`, `0x200`.
+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-образцы.
-Для инструментов:
+Что нужно собрать, чтобы закрыть это полностью:
-- strict validator по разделу 7.1;
-- canonical writer по разделу 7.4;
-- opaque-представление command-body для безопасного round-trip.
+- frame-by-frame dump из оригинального runtime (alpha, manager flags, per-command state);
+- контрольные прогоны при фиксированном `dt` и seed;
+- минимум по одному ресурсу на каждую редкую ветку (`op6`, op1-tail с ненулевыми `+136..223`).
Copyright © 2026 Valentin A. Popov. All Rights Reverse Engineered.