Перейти к содержанию

Архитектура

back2mw — конвертер содержимого Oblivion (позже Skyrim) в формат Morrowind. Rust, один статический бинарь, разрешительная лицензия.


Раскладка

back2mw/
├── CLAUDE.md                  правила для исполнителя задач
├── README.md                  вход в репозиторий
├── Cargo.toml                 workspace, общие lints и зависимости
├── rust-toolchain.toml        канал stable + rustfmt, clippy
├── zensical.toml, zensical.en.toml   сайт документации: русский и английский
├── .github/                   workflows ci, docs, release; scripts/changelog.sh
├── packaging/                 README.txt и config.example.toml для архива релиза
├── crates/
│   ├── lang/                  язык сообщений (русский, английский): один на процесс, виден всем
│   │                          крейтам, сам без зависимостей
│   ├── tes4_read/             чтение источника. Про TES3 не знает НИЧЕГО
│   │   ├── container.rs       дерево GRUP, заголовки 20 (TES4) / 24 (TES5) байта, zlib
│   │   ├── schema.rs          механизм декларативных спеков полей (Fields, FromFields)
│   │   ├── records/           спека на тип записи: stat, weap, worn (ARMO, CLOT), item, magic,
│   │   │                      effects, leveled, world (ACTI, DOOR, CONT, LIGH…), exterior (WRLD,
│   │   │                      CELL, REFR, LTEX, REGN, WTHR), land, pathgrid, actor (RACE, CLAS,
│   │   │                      FACT, NPC_), creature, sound, dialogue, global
│   │   ├── world_tree.rs      обход worldspace: ячейки, их LAND и размещения
│   │   ├── dialogue_tree.rs   темы диалога и их реплики в дереве групп
│   │   ├── bsa.rs             ридер BSA v103 (Oblivion)
│   │   ├── cp1252.rs          декодер строк
│   │   ├── error.rs           ошибки с позицией в файле
│   │   └── synth.rs           сборка синтетических плагинов для тестов
│   ├── transform/             ЕДИНСТВЕННОЕ место, знающее записи обеих игр
│   │   ├── ids.rs, paths.rs   FormID → строковый ID; короткие пути мешей, иконок, картинок книг
│   │   ├── objects.rs         объекты с мешем: STAT, WEAP, ARMO/CLOT, предметы, объекты мира, TREE
│   │   ├── weapons.rs, worn.rs, items.rs, world.rs   характеристики оружия; броня и одежда;
│   │   │                      предметы инвентаря; ACTI, DOOR, CONT, LIGH, FLOR, FURN, GRAS
│   │   ├── effects.rs, magic.rs, leveled.rs, prices.rs   эффекты по таблице; ENCH и SPEL; LVLI →
│   │   │                      LEVI; подтяжка цен к Morrowind
│   │   ├── exterior.rs, interior.rs   worldspace → CELL, LAND, LTEX, REGN, ссылки (слияние 2×2,
│   │   │                      смещение); интерьеры, достижимые дверями
│   │   ├── land.rs, pathgrid.rs, weather.rs   кодек VHGT, сшивка 65×65, VTEX, WNAM; PGRD; тип
│   │   │                      погоды и шансы региона
│   │   ├── npcs.rs, races.rs, classes.rs, factions.rs, skills.rs   NPC с автоподсчётом, расы,
│   │   │                      классы, фракции, навыки 21 → 27
│   │   ├── creatures.rs, creature_lists.rs, globals.rs   существа на донорах и со своей
│   │   │                      моделью; LVLC → LEVC;
│   │   │                      глобальные переменные
│   │   ├── sounds.rs          SOUN, звуки регионов, размещённые звуки и петли
│   │   └── dialogue.rs, dialogue/   отбор реплик; темы, приветствия, голос и убеждение
│   ├── mesh_convert/          ЕДИНСТВЕННОЕ место, знающее обе стороны NIF; ещё текстуры лиц,
│   │   │                      иконки и звук
│   │   ├── read/              разбор NIF Oblivion (20.0.0.4/5, 10.x) — свой, библиотеки нет
│   │   ├── geometry.rs        NiTriStrips → NiTriShape
│   │   ├── material.rs        свойства материала 20.0.0.x → 4.0.0.2 по полям
│   │   ├── textures.rs        текстуры НЕ конвертируются, а копируются: отбор выживших слотов,
│   │   │                      переписывание путей, разведение коллизий имён
│   │   ├── collision.rs       bhk* → RootCollisionNode, havok-юниты × 7
│   │   ├── door.rs            петля двери по анимации Open; перенос начала координат меша
│   │   ├── particles.rs       NiParticleSystem → эмиттер Morrowind
│   │   ├── skin.rs            броня и одежда на скелет Morrowind
│   │   ├── creature.rs, creature/   своя модель существа: тело из скелета и частей; лента
│   │   │                      анимации из клипов (группы — по data/creature_groups.tsv)
│   │   ├── facegen.rs, head.rs, face_texture.rs   .egm/.egt/.tri; голова NPC; запечённая кожа лица
│   │   ├── speedtree.rs, speedtree/   .spt → геометрия дерева → NIF
│   │   ├── icons.rs           иконки инвентаря под размер Morrowind
│   │   └── audio.rs, audio/mp3.rs   WAV стерео → моно; склейка mp3 голосов по кадрам
│   ├── tes3_out/              ЕДИНСТВЕННОЕ место, знающее записи плагина TES3
│   │   ├── model.rs           модель цели: простые структуры без типов tes3::…
│   │   ├── records.rs         модель → записи tes3::esp
│   │   ├── plugin.rs          PluginBuilder: сборка и запись .esp/.esm
│   │   ├── world.rs           LTEX, REGN, внешние CELL со ссылками, LAND, PGRD
│   │   ├── actors.rs, dialogue.rs, scripts.rs   RACE, CLAS, FACT, NPC_; DIAL/INFO; SCPT по шаблонам
│   │   ├── vanilla.rs         чтение ванильных файлов Morrowind из установки игрока
│   │   └── archive.rs         запись BSA TES3 (через tes3::bsa)
│   ├── back2mw/               библиотека и консольный бинарь: стадии, файловая система, CLI
│   │   ├── main.rs            CLI: разбор флагов, выбор языка, вывод
│   │   ├── config.rs, settings.rs   config.toml: чтение консолью; запись окном
│   │   ├── pipeline.rs        прогон all: плагины Oblivion → готовый мод в output/
│   │   ├── extract.rs, validate.rs, package.rs, install.rs   стадии
│   │   ├── bodies.rs, faces.rs, creature_models.rs, dialogue.rs   части прогона: тела, лица,
│   │   │                      модели существ, диалоги
│   │   ├── job.rs             задание окна: собрать, упаковать, установить
│   │   └── detect.rs, plugins.rs, worlds.rs   поиск игр, список плагинов и миров для окна
│   └── gui/                   окно (egui): тонкая обёртка над библиотекой back2mw
├── data/                      КОНТЕНТ, не код: таблицы соответствий (*.tsv) и anchors/value.tsv
└── docs/                      эта документация (ru/, en/), gen_tables.py, notes_en.tsv

Тесты лежат в крейтах: unit-тесты в #[cfg(test)] mod tests рядом с кодом, интеграционные в crates/<крейт>/tests/. Отдельных корневых tests/ и testdata/ нет и не нужно: синтетические входы строятся кодом (tes4_read::synth), а не лежат файлами. Если понадобятся файловые фикстуры — crates/<крейт>/tests/data/, и только синтетика.

Рабочие каталоги (work/, output/, sources/) создаются рядом с бинарём на машине пользователя и в репозитории не лежат — см. pipeline.md.


Обязанности крейтов и границы

Крейт Знает про НЕ знает про Зависит от
tes4_read форматы TES4/TES5: плагины и BSA что-либо про TES3 flate2
transform записи обеих игр — здесь все преобразования записей байтовые раскладки, NIF tes4_read, tes3_out (с T1.8)
mesh_convert NIF обеих версий записи плагинов tes3 с фичей nif (с T1.4)
tes3_out записи плагина TES3, BSA TES3 форматы источника tes3 с фичами esp, bsa
back2mw порядок стадий, файловую систему, CLI детали любого формата все четыре
gui окно всё, кроме API back2mw back2mw, eframe, rfd
lang язык сообщений: русский или английский, один на процесс всё остальное ничего

От lang зависят все крейты выше: сообщения собираются в строки там, где возникают, поэтому язык нельзя передать параметром — пришлось бы тянуть его через каждую функцию.

Решения о границах, принятые 2026-09-24

Были не записаны и противоречили друг другу; исполнитель задач упёрся бы в них на T1.4 и T1.8.

Р1. transform зависит от tes3_out, а не наоборот. tes3_out отдаёт свою модель цели — простые структуры Rust (PluginBuilder::add_static(id, mesh) уже так устроен) — и не выставляет наружу типы tes3::…. transform берёт типы источника из tes4_read и вызывает API tes3_out. Следствие для теста границ: cargo tree показывает транзитивные зависимости, и tes3 через tes3_out будет виден в дереве transform. Поэтому проверка «transform не знает раскладку TES3» меняется на прямые зависимости (--depth 1): transform не зависит от tes3 напрямую. Изменено в T1.8 (2026-09-24), осознанно, а не молча — это и есть долг фазы 0.

Р2. NIF 4.0.0.2 пишет mesh_convert сам, через tes3::nif. В прежней раскладке стоял tes3_out/nif.rs, но тогда mesh_convert должен был бы выдавать промежуточную модель сцены NIF, а tes3_out — её дублировать блок за блоком. Библиотека и так держит байтовую раскладку NIF; mesh_convert строит tes3::nif::NiStream и сохраняет его. Правило 2 ниже сформулировано под это.

Р3. BSA источника читает tes4_read::bsa, BSA цели пишет tes3_out::archive. tes3::bsa умеет только формат TES3 (магия 0x00000100), архивы Oblivion v103 он не читает.

Р4. Пин tes3 один на весь workspace. Как только tes3 понадобится второму крейту (T1.4), зависимость переезжает в [workspace.dependencies] корневого Cargo.toml с default-features = false, а крейты включают свои фичи. Два разных rev в одном workspace — ошибка.

Правила, которые проверяются автоматически

  1. tes4_read не импортирует tes3_out, transform, mesh_convert, tes3; tes3_out не импортирует tes4_read, transform, mesh_convert. Всё знание «как одно превращается в другое» живёт в transform (записи) и mesh_convert (меши).
  2. Раскладка байтов TES3 — только в tes3::…, и доступ к ней только из tes3_out (плагины, архивы) и mesh_convert (NIF). Именно этого не сделал референс: у него TES5 растворён более чем в 100 файлах, и поэтому второй целевой формат туда уже не добавить.

  3. lang не зависит ни от чего — ни от наших крейтов, ни от внешних: иначе через общий для всех крейт они узнали бы друг о друге в обход правил 1 и 2 (добавлено 2026-10-01 решением владельца).

Проверка — crates/back2mw/tests/dependency_boundaries.rs, который разбирает вывод cargo tree. Любое изменение этих правил — решение владельца проекта, а не исполнителя.


Внешние зависимости

Зависимость Лицензия Роль
Greatness7/tes3 MIT OR Apache-2.0 Вся выходная сторона: записи .esp/.esm (esp), NIF 4.0.0.2 (nif), BSA TES3 (bsa). Через git с пином коммита e61ad140b51d889ae5aa30914ba2a20fd51bf2e0 — API нестабилен. Ветка main, не master
flate2 MIT/Apache распаковка zlib-записей плагинов и файлов BSA
serde, toml MIT/Apache разбор и запись config.toml (back2mw)
zip MIT раздаточный zip стадии package, только deflate (back2mw)
eframe (egui), rfd MIT/Apache окно и диалог выбора папки (gui)
iced-x86 MIT только в тестах mesh_convert: дизассемблер для сверки SpeedTree с Oblivion.exe

Не понадобились: rayon (в скорость пока не упёрлись) и ffmpeg — звуки и голоса Oblivion в тех же форматах, что у Morrowind, перекодировать нечего.

Новая зависимость — только если без неё задача заметно сложнее, и с лицензией MIT/Apache/BSD/Zlib. GPL/LGPL в дереве зависимостей — нельзя.

Не берём: libloadorder и esplugin — GPL-3.0, а esplugin по своему же README не general-purpose парсер и полей записей не отдаёт, то есть нужную нам работу всё равно не делает. Чтение [Game Files] из Morrowind.ini — задача на десятки строк.

Внимание на ловушку: крейт tes3 на crates.io — не библиотека Greatness7, а занятое имя (v0.1.0 от 2021, 9 загрузок за 90 дней).

Инструменты проверки (не зависимости продукта)

esmtool, niftest, bsatool из OpenMW плюс Morrowind Construction Set. Это внешние валидаторы, запускаемые стадией validate и тестами. OpenMW никогда не цель исполнения — там, где он мягче ванили, его «ок» ничего не доказывает. Где лежат и как их передать тестам — раздел «Тесты на реальных данных» в руководстве разработчика.


Где что лежит по типу

  • Код — crates/. Никаких таблиц контента внутри модулей.
  • Контент — data/. Таблицы соответствий и опорных точек (эффекты, погода, цены) — это данные, которые правит человек, а не логика. Референс здесь ошибся: у него 1.4 МБ рукописного текста лежит в каталоге сгенерированного кода с пометкой «DO NOT REGENERATE».
  • Синтетические тестовые входы — строятся кодом в тестах. Ассетов Bethesda в репозитории не бывает никогда, ни в каком виде; .gitignore отсекает *.esm, *.esp, *.bsa, *.nif, *.kf, *.dds.
  • Знание форматов — docs/ru/formats/ (и перевод — docs/en/formats/). Каждый факт с пометкой, проверен он или нет, и откуда взят.