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