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