Архитектура¶
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 — ошибка.
Правила, которые проверяются автоматически¶
tes4_readне импортируетtes3_out,transform,mesh_convert,tes3;tes3_outне импортируетtes4_read,transform,mesh_convert. Всё знание «как одно превращается в другое» живёт вtransform(записи) иmesh_convert(меши).-
Раскладка байтов TES3 — только в
tes3::…, и доступ к ней только изtes3_out(плагины, архивы) иmesh_convert(NIF). Именно этого не сделал референс: у него TES5 растворён более чем в 100 файлах, и поэтому второй целевой формат туда уже не добавить. -
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/). Каждый факт с пометкой, проверен он или нет, и откуда взят.