fabrilis/docs/ARCHITECTURE.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

6.6 KiB
Raw Blame History

Архитектура

Принципы

  • Cargo workspace из маленьких crate'ов. Симуляция — чистый Rust без GPU и без Bevy.
  • Зависимости идут только вниз. Подсистемы друг о друге не знают; их соединяют bridge и планировщик из core.
  • Одно приложение, три режима — пресеты Fidelity (см. MODES.md).
  • Рендер только читает снимок состояния и не влияет на симуляцию.

Слои и crate'ы

Слой Crate Роль Зависит от
Ядро core СИ-единицы, время (u64 нс), планировщик, Fidelity, снимки, math, vec (Vec3/Mat3/Quat/Transform) —
platform топология P/E-ядер, GPU, бенчмарки, регулятор core
storage форматы, миграции, blob по хешу, папка проекта core
Данные materials материалы, масса/инерция по мешу, прочность core
scene сцена и конструкция, импорт мешей core, materials, storage
parts библиотека деталей (данные + плагины), BOM core, materials, scene
Физика physics трейт PhysicsBackend, Rapier, шарниры, трение core
structure балки, FEM, напряжения, разрушение core, materials
thermal тепло, вентиляция core, materials
aero аэродинамика, ветер core
actuators мышцы, серво, моторы core
Электроника analog MNA-решатель схем core
wiring жгуты проводов core, analog, thermal
cpu трейт Cpu, RISC-V (потом arm/avr) core
soc шина, периферия, device tree, virtio core, cpu
sensors IMU, энкодеры, токовые датчики, модели шума и задержки core
bridge пины ↔ схема ↔ приводы ↔ физика core, soc, analog, actuators, physics
Мир worldgen шум, высотная карта, чанки core
Верх scripting Rhai, сценарии опытов core
analysis описания опытов, развёрток, Monte Carlo и метрик устойчивости; исполняет их app через трейт Experiment core
modes Bench / Lab / World почти все
render wgpu: clipmap, инстансинг, режимы вида core
ui свой immediate-mode UI на нашем рендере: редактор, инспектор, графики, event-driven redraw core, render
app winit, главный цикл core, platform, storage, modes, render, ui

Поток данных за такт

  1. Планировщик (core::sched) делит время на эпохи по наибольшему периоду.
  2. Внутри эпохи подсистемы делают свои шаги с фиксированным порядком; шаг режется ближайшим событием из очереди (COUPLING.md).
  3. Обмен только в точках синхронизации через bridge (защёлкнутые значения); сильные связи решаются совместно, а не запаздыванием.
  4. В конце эпохи пишется Snapshot: набор подснимков, по одному от подсистемы.
  5. render и ui читают снимок; storage сохраняет по запросу.

analysis не запускает симуляцию сам: он описывает опыт (параметры, seeds, проверки) и метрики, а прогон выполняет app через трейт Experiment. Иначе analysis пришлось бы тянуть вверх все подсистемы и получить цикл слоёв.

Бюджет производительности

Эталонная сцена — паук: 24 тела, 32 шарнира, 8 аналоговых узлов, 12 датчиков, физика 1 кГц. Цель — RTF ≥ 1 на машине с RX 470 (AMD, 2016) при 60 кадрах. Бюджет такта World: 0.5 мс на физику, 0.2 мс на электронику и датчики, остальное на подготовку снимка. Бюджет проверяется бенчмарком в автоматическом прогоне; выход за него — повод переходить на ash (D24) или упрощать World, но не менять шаг.

Адаптация под устройство

platform определяет ядра (P/E), SIMD, RAM, GPU и кеширует профиль. Адаптируется только то, что не влияет на результат: число потоков, раскладка по ядрам, качество рендера, место culling. Модели (Fidelity) от железа не зависят. Подробно: DETERMINISM.md.

Расширяемость

Новая деталь = данные (RON) + при необходимости плагин с трейтом из parts::plugin. Ядро править не нужно.

Структура репозитория

fabrilis/
├── Cargo.toml, rustfmt.toml, clippy.toml, rust-toolchain.toml, LICENSE (MIT), TODO.md
├── docs/            документация (не подпадает под правила кода)
├── crates/          24 crate'а симуляции, рендера и приложения
├── tools/limits/    проверка правил (CODE_RULES.md), вызывается из build.rs
├── tools/measure_deps.py  замер веса кандидатов в зависимости
├── examples/        эталонные конструкции (первый: мех-паук)
├── ref/             клоны чужих проектов для чтения (gitignored, не проверяются)
└── .githooks/       pre-commit: правила, fmt, clippy

Слои зависимостей закодированы в tools/limits/src/rules/layers.rs; новый crate нужно внести туда, иначе сборка падает.