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

80 lines
6.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Архитектура
## Принципы
- 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
нужно внести туда, иначе сборка падает.