fabrilis/docs/ARCHITECTURE.md
loki5512344 878d144b77 Initial commit: Fabrilis docs, rules and deterministic core
Docs (architecture, decisions, coupling, determinism, UI, references), code rules enforced by tools/limits, deterministic core with units, time, math, sched, snapshot, vec and rng, plus smoke tests. ref/ stays out of git.
2026-11-16 23:06:29 +01:00

81 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 мс на электронику и датчики, остальное
на подготовку снимка. Бюджет проверяется бенчмарком в CI; выход за него — повод
переходить на `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
└── .github/ CI на Linux, Windows, macOS
```
Слои зависимостей закодированы в `tools/limits/src/rules/layers.rs`; новый crate
нужно внести туда, иначе сборка падает.