fabrilis/docs/ARCHITECTURE.md
loki5512344 1042269d7e
Finish M4: cart, log facade, idle diagnostics and terrain LOD
Add the core::log facade with five levels and a sink; migrate the app dev log and enable trace in --dev. Replace the dropped cubes with a four-wheel cart on revolute joints driven by velocity motors, add WASD controls, a golden trajectory and a slope test. Instrument idle frame spikes and throttle the window title. Add chunked terrain LOD with skirts (2368 vs 8192 triangles) while physics keeps the full mesh. Pin Rust 1.100.0; edition stays 2024.
2026-11-17 14:32:52 +01:00

103 lines
8.6 KiB
Markdown
Raw Permalink 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, но не менять шаг.
## Рельеф и LOD
`worldgen::terrain` строит высотную карту и один меш на её основе (D14). Первый шаг
LOD — chunked LOD без отдельного прохода рендера:
- карта режется на чанки по `LodConfig::chunk_cells` клеток, последний чанк короче;
- внутри чанка остаются каждый `step`-й узел, `step` — степень двойки не больше
`max_step` и размера чанка; шаг растёт с расстоянием от камеры до центра чанка
(`switch_m` на удвоение);
- по периметру каждого чанка идёт вертикальная юбка глубиной `skirt_m`, она
закрывает трещины между соседями с разным шагом и не меняет верхнюю поверхность;
- приложение хранит центр, от которого построен меш, и пересобирает его, когда
камера сместилась на `LOD_REBUILD_M` (4 м); между перестроениями кадр платит
только проверку расстояния.
Результат по-прежнему один `TerrainMesh` в сцене, поэтому рендер не менялся.
Физика работает на полном меше `heightmap.mesh()`: LOD облегчает только картинку
и не влияет на столкновения или детерминизм симуляции.
Это честно первый шаг: шаг выбирается по расстоянию до чанка, а не по экранной
ошибке, и границы чанков могут заметно переключаться при движении. Продолжение —
rings/clipmap с сеткой, сшитой без юбок, и выбором детализации по проекции ошибки
на экран.
## Адаптация под устройство
`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
нужно внести туда, иначе сборка падает.