fabrilis/docs/DECISIONS.md
loki5512344 190ef9cc4b Add design persistence, world rendering, metrics overlay and logs
M3: STL/OBJ import with mesh validation, mass/COM/inertia, material database, RON scene with content-addressed blobs and v0->v1 migration. M4: deterministic heightmap terrain, trimesh colliders, wgpu renderer with instancing and depth, winit app with 1 kHz physics, fly camera, on-screen metrics overlay and per-frame CSV/dev logs. Docs: UI, logging, network and headless CLI plans.
2026-11-16 23:40:39 +01:00

11 KiB
Raw Permalink Blame History

Решения

# Решение Почему
D1 Multi-crate workspace, симуляция без GPU/Bevy тесты без окна, автоматические прогоны, детерминизм
D2 Без Bevy; свой рендер на wgpu (Vulkan); без общего ECS, данные SoA внутри crate'ов RX 470 слабая, нужен контроль; рендер заменяем
D3 Физика: гибрид. PhysicsBackend + rapier3d-f64 с enhanced-determinism на старте, нужное заменяем своим быстрый старт без потери контроля и без границы f32
D4 Механика: жёсткие тела + нагрузки на шарниры (World); балки и FEM (Lab); разрушение точность там, где нужна
D5 ISA: RISC-V первым (RV32IMAC, RV64GC), остальные через трейт Cpu пользователь знает RISC-V, Linux, открытая ISA
D6 Электроника в два слоя: цифровая эмуляция SoC + аналоговый MNA + bridge запуск реального Linux/прошивок + реальное питание
D7 Один бинарник, режимы Bench/Lab/World — пресеты Fidelity один паук и детали во всех режимах
D8 Детерминизм: целое время, свой math, порядок независим от потоков воспроизводимость, перемотка, golden-тесты
D9 Управление временем отдельно от Fidelity: dt не меняется замедление ничего не огрубляет
D10 Адаптация под железо: P/E-ядра, GPU только для неавторитетного одинаковый результат у всех
D11 Сохранения: папка проекта, RON, снимки отдельно, настройки в XDG git-friendly, командная работа
D12 Скрипты: Rhai чистый Rust, песочница, без C-зависимостей
D13 Лимиты: файл >350 строк — предупреждение, >500 — ошибка сборки; ≤4 файла кода в каждой директории (подпапки не считаются, вложенность любая). Тестовые файлы (tests.rs, tests/, benches/) не считаются и по размеру не ограничены см. CODE_RULES.md
D14 Террейн: высотная карта + clipmap, без вокселей; генерация на CPU одна карта для рендера и коллайдеров
D15 Деталь = данные + плагин; из конструкции экспортируется BOM цель: собрать конструкцию в реальности
D16 Цель проекта: универсальная платформа проектирования любых механизмов; паук — эталонный проект в examples/, в движке нет кода под него расширяемость, любые будущие конструкции
D17 Сценарии и анализ — часть ядра платформы: crate analysis (развёртки, Monte Carlo, метрики устойчивости, отказы) и sensors (IMU, энкодеры, шум) проверка стабилизации и работы контроллеров
D18 Правила репозитория проверяются кодом (tools/limits в build.rs каждого crate'а): размеры, комментарии на английском, тесты отдельно, слои crate'ов нарушение ломает сборку, правила не держатся на дисциплине
D19 Лицензия MIT: код можно брать и менять, но нужно сохранять упоминание авторов; правообладатель и автор: loki простая разрешающая лицензия с обязательной атрибуцией
D20 UI свой, на нашем рендере (прямоугольники, текст, виджеты, графики); egui и другие готовые UI-библиотеки не берём пользователь их не любит; мы всё равно владеем рендером
D21 Векторная математика своя в core (Vec3, Mat3, Quat, Transform на f64 через core::math); glam и nalgebra в симуляции не используем детерминизм: их тригонометрия идёт через системный libm
D22 Импорт мешей свой: STL и OBJ пишем сами, glTF сначала минимальным своим читателем gltf тянет 37 crate'ов ради простого формата
D23 Крупные зависимости: wgpu, winit, rapier3d-f64, rhai принимаем пока, остальное своё; proptest и criterion — только dev-зависимости (D26) см. DEPENDENCIES.md
D24 Рендер на wgpu; запасной вариант — ash (Vulkan напрямую). Переход, если сборка wgpu (61 crate) или размер станут проблемой рендер скрыт за crate'ом render, замена не заденет симуляцию
D25 Название проекта: Fabrilis (лат. fabrilis, «относящийся к мастеру, ремесленнику»); автор: loki; префикс crate'ов fabrilis- свободно на crates.io; латынь по вкусу автора
D26 proptest и criterion разрешены как dev-зависимости; основные тесты — свои на seeded core::rng в продуктовую сборку dev-зависимости не входят, экономить на них незачем; свой генератор всё равно нужен для Monte Carlo
D27 Этапы — вертикальные срезы с критерием готовности (DoD); каждая веха даёт демонстрируемый результат горизонтальный план даёт годы без рабочего инструмента
D28 Детерминизм в трёх уровнях: D1 повтор на машине, D2 при любом числе потоков, D3 на разных ОС и архитектурах. Авторитетная сборка — базовый target-cpu, SIMD только явными ядрами честная граница гарантии вместо одного невыполнимого обещания
D29 Шаг физики World — 1 кГц (1 мс); Bench и Lab не огрубляются, а замедляются 250 Гц разъезжается по фазе с контактом стопы и жёстким шарниром
D30 Проект публичный, но до 0.6.0 API плагинов и форматов нестабилен; обратная совместимость не обещается ещё рано замораживать интерфейсы, а публичность задаёт планку документации
D31 Углы — newtype Radians; градусы только в интерфейсе и при импорте градусы и радианы иначе путаются молча
D32 Очередь событий с метками в нс в планировщике: событие делит шаг подсистемы фронты PWM и прерывания нельзя привязывать к эпохам
D33 Версия компилятора зафиксирована rust-toolchain.toml; автоматический прогон собирает базовую и native сборки и сверяет хеши разные LLVM могут разойтись в последних битах
D34 UI — свой immediate-mode слой на нашем wgpu-рендере с event-driven redraw; retained-дерево только по профилировке. ShapeUI blueprint — источник контрактов, не фундамент редактору нужны панели, дерево и графики, а не окна произвольной формы; UI-фреймворк на годы остановил бы проект
D35 Логи — собственный фасад core::log с уровнями error/warn/info/debug/trace; приложение ставит приёмник, --dev включает debug/trace; логи не влияют на симуляцию единый способ писать диагностику с первого дня, без внешних зависимостей и без влияния на детерминизм; log/tracing можно подключить позже
D36 Headless CLI — пульт управления движком и расчётный инструмент, отдельным бинарником без render/ui/winit; общий прогон мира живёт в modes. Внешние скрипты, агенты и нейросети управляют командами (JSON-RPC, позже MCP), логика остаётся снаружи один протокол для прогонов, сервера и агентов; движок остаётся симулятором, а не чужим рантаймом

Открытые вопросы

  • FEM: тетраэдры для всей детали или балки + локальные тетраэдры в узлах.
  • Модель разрушения: порог по напряжению, трещины, усталость.
  • Воздушные потоки: сеть каналов (быстро) или CFD-lite (точно).
  • Сходимость MNA: набор приёмов (gmin stepping, source stepping, breakpoints) и предельное число делений шага.
  • Коллизии: parry оставляем навсегда или пишем свой узкий слой после своего физического backend'а.
  • Когда переходить с wgpu на ash (D24): после M4 по времени сборки и RTF.
  • Сетевой режим: транспорт (TCP или сразу QUIC), частота снапшотов, нужен ли предсказанный ввод; см. NETWORK.md.
  • Shaping и IME для текстовых полей: cosmic-text или Parley; решаем на M10.
  • Нужен ли retained-слой UI: решаем по профилировке M10.
  • Конкретная целевая плата и список реальных компонентов.