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

8.6 KiB
Raw Permalink Blame History

Архитектура

Принципы

  • 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 нужно внести туда, иначе сборка падает.