Add design persistence, world rendering, metrics overlay and logs
M3: STL/OBJ import with mesh validation, mass/COM/inertia, material database, RON scene with content-addressed blobs and v0->v1 migration. M4: deterministic heightmap terrain, trimesh colliders, wgpu renderer with instancing and depth, winit app with 1 kHz physics, fly camera, on-screen metrics overlay and per-frame CSV/dev logs. Docs: UI, logging, network and headless CLI plans.
This commit is contained in:
parent
878d144b77
commit
190ef9cc4b
111 changed files with 14801 additions and 63 deletions
|
|
@ -52,7 +52,7 @@
|
|||
Эталонная сцена — паук: 24 тела, 32 шарнира, 8 аналоговых узлов, 12 датчиков,
|
||||
физика 1 кГц. Цель — RTF ≥ 1 на машине с RX 470 (AMD, 2016) при 60 кадрах.
|
||||
Бюджет такта World: 0.5 мс на физику, 0.2 мс на электронику и датчики, остальное
|
||||
на подготовку снимка. Бюджет проверяется бенчмарком в CI; выход за него — повод
|
||||
на подготовку снимка. Бюджет проверяется бенчмарком в автоматическом прогоне; выход за него — повод
|
||||
переходить на `ash` (D24) или упрощать World, но не менять шаг.
|
||||
|
||||
## Адаптация под устройство
|
||||
|
|
@ -74,8 +74,7 @@ fabrilis/
|
|||
├── tools/measure_deps.py замер веса кандидатов в зависимости
|
||||
├── examples/ эталонные конструкции (первый: мех-паук)
|
||||
├── ref/ клоны чужих проектов для чтения (gitignored, не проверяются)
|
||||
├── .githooks/ pre-commit: правила, fmt, clippy
|
||||
└── .github/ CI на Linux, Windows, macOS
|
||||
└── .githooks/ pre-commit: правила, fmt, clippy
|
||||
```
|
||||
Слои зависимостей закодированы в `tools/limits/src/rules/layers.rs`; новый crate
|
||||
нужно внести туда, иначе сборка падает.
|
||||
|
|
|
|||
116
docs/CLI.md
Normal file
116
docs/CLI.md
Normal file
|
|
@ -0,0 +1,116 @@
|
|||
# Headless CLI
|
||||
|
||||
CLI — это пульт управления движком и расчётный инструмент: пакетные прогоны и
|
||||
живая консоль. Внешняя программа — скрипт, агент, нейросеть — управляет движком
|
||||
командами, как инструментами через MCP. Окно и GPU не нужны.
|
||||
|
||||
Отдельный бинарник, который не зависит от `render`, `ui` и `winit`; общий код мира
|
||||
и прогонов живёт в `modes`, чтобы GUI и CLI считали одно и то же.
|
||||
|
||||
## Зачем
|
||||
|
||||
- прогнать сценарий на сервере и получить CSV/отчёт;
|
||||
- проверить регрессии автоматическим прогоном без дисплея;
|
||||
- считать развёртки и Monte Carlo;
|
||||
- держать один сервер физики и подключать клиентов (NETWORK.md);
|
||||
- дать внешнему коду команды `open/run/step/set_actuator/read_sensor`, не встраивая
|
||||
чужую логику в движок;
|
||||
- позволить агенту или нейросети вести эксперимент по шагам и читать только датчики.
|
||||
|
||||
## Команды (план)
|
||||
|
||||
| Команда | Что делает |
|
||||
|---|---|
|
||||
| `fabrilis simulate <проект> --scenario <id> --seed N --until T --out result.csv` | один детерминированный прогон |
|
||||
| `fabrilis validate` | проверки из VALIDATION.md; код возврата 1 при провале допуска |
|
||||
| `fabrilis sweep <проект> --params sweep.ron --out dir/` | сетка/Монте-Карло, по процессу на прогон |
|
||||
| `fabrilis control --stdio` | протокол команд по stdin/stdout для скрипта/агента |
|
||||
| `fabrilis serve --bind 0.0.0.0:9000` | headless-сервер физики (S1 из NETWORK.md) |
|
||||
| `fabrilis repl --connect <сокет>` | живая консоль: команды в запущенный движок |
|
||||
| `fabrilis info` | версии, возможности, доступные сценарии |
|
||||
|
||||
Коды возврата: `0` — успех, `1` — провал проверки, `2` — ошибка аргументов,
|
||||
`3` — ошибка выполнения.
|
||||
|
||||
## Гарантии
|
||||
|
||||
- Без GPU и окна; шаг физики фиксированный, как в мире.
|
||||
- Один seed и одни входы дают один результат; golden-хеш проверяется автоматическим прогоном.
|
||||
- Параллельные прогоны — отдельные процессы, результат не зависит от их числа.
|
||||
- Логи по LOGGING.md: обычный уровень `info`, `--dev` — `debug/trace`.
|
||||
- Метрики-лог CSV и dev-лог те же, что у GUI (LOGGING.md).
|
||||
|
||||
## Пульт управления (протокол команд)
|
||||
|
||||
Один и тот же набор команд доступен из CLI, из Unix-сокета/TCP и (позже) как
|
||||
MCP-инструменты. Это не «обучение в движке»: внешний код решает, что делать, а
|
||||
движок исполняет команды и возвращает состояние.
|
||||
|
||||
Транспорт v1 — JSON-RPC 2.0, по сообщению на строку: stdio для `fabrilis control`,
|
||||
Unix-сокет для локального агента, TCP с токеном для удалённого сервера.
|
||||
|
||||
```text
|
||||
-> {"jsonrpc":"2.0","id":1,"method":"engine.open","params":{"project":"cart","seed":42}}
|
||||
<- {"jsonrpc":"2.0","id":1,"result":{"t":0.0,"bodies":3}}
|
||||
-> {"jsonrpc":"2.0","id":2,"method":"engine.step","params":{"steps":10}}
|
||||
<- {"jsonrpc":"2.0","id":2,"result":{"t":0.01,"events":[]}}
|
||||
-> {"jsonrpc":"2.0","id":3,"method":"engine.set_actuator","params":{"joint":0,"torque":4.9}}
|
||||
-> {"jsonrpc":"2.0","id":4,"method":"engine.read_sensor","params":{"sensor":"encoder0"}}
|
||||
<- {"jsonrpc":"2.0","id":4,"result":{"angle":0.31,"t":0.01}}
|
||||
```
|
||||
|
||||
| Команда | Смысл |
|
||||
|---|---|
|
||||
| `engine.open` / `engine.close` | открыть проект/сценарий, освободить |
|
||||
| `engine.run` / `engine.pause` | идти по часам или стоять |
|
||||
| `engine.step` | ровно N шагов, без ожидания реального времени |
|
||||
| `engine.reset` | вернуть сцену к seed/снимку |
|
||||
| `engine.set_actuator` | момент/цель/скорость привода |
|
||||
| `engine.set_input` | GPIO/PWM/вход схемы |
|
||||
| `engine.read_sensor` | энкодер, IMU, ток, температура |
|
||||
| `engine.query_state` | позы, метрики, флаги (только разрешённое) |
|
||||
| `engine.snapshot` / `engine.restore` | снимок и откат |
|
||||
| `engine.save` | сохранить проект/результат |
|
||||
|
||||
Правила:
|
||||
|
||||
- команды применяются на границе шага, а не посреди решателя; ответ подтверждает,
|
||||
на каком времени они применены;
|
||||
- наблюдение для внешнего управления — только датчики (`sensors`), без ground truth;
|
||||
`query_state` — для отладки и разрешён явно;
|
||||
- шаг фиксированный; `engine.step` не зависит от реального времени;
|
||||
- один процесс — одна сцена; несколько внешних клиентов подключаются к `serve`
|
||||
(NETWORK.md);
|
||||
- одинаковые seed и последовательность команд дают одинаковую траекторию;
|
||||
- MCP-адаптер (позже) выставляет те же команды как инструменты с явным allowlist,
|
||||
без доступа к файлам и сети за пределами проекта.
|
||||
|
||||
## Внешние контроллеры
|
||||
|
||||
Для обучения или скриптового управления используется тот же протокол: `reset`,
|
||||
`step`, `set_actuator`, `read_sensor`. Reward и условие `done` задаёт сценарий, а
|
||||
не ядро; один процесс — одна среда, вектор сред делает внешний код. Позже, если
|
||||
JSON-RPC не хватит по скорости, добавим бинарный протокол или PyO3-биндинги.
|
||||
|
||||
## Разрез работ
|
||||
|
||||
- **C1** — бинарник `fabrilis-cli` и `simulate`: тот же мир без окна, CSV на выходе;
|
||||
DoD: прогон тестовой сцены, golden-хеш, нет зависимости от `render`/`ui`.
|
||||
- **C2** — `validate` и коды возврата; DoD: специально сломанный кейс даёт код 1.
|
||||
- **C3** — `sweep` и Monte Carlo по процессам; DoD: N прогонов, результат не зависит
|
||||
от числа процессов.
|
||||
- **C4** — протокол команд (JSON-RPC, stdio/Unix-сокет) и `repl`; DoD: внешний
|
||||
скрипт делает open/reset/step/set_actuator/read_sensor и получает детерминированную
|
||||
траекторию.
|
||||
- **C5** — `serve`; DoD: headless-сервер и клиент из NETWORK.md S1–S2.
|
||||
- **C6** — MCP-адаптер поверх тех же команд; DoD: агент открывает сцену, шагает,
|
||||
читает датчики и снимок, не имея доступа к файлам вне проекта.
|
||||
|
||||
## Открыто
|
||||
|
||||
- Один бинарник с подкомандами или отдельные `fabrilis-cli`/`fabrilis-server`.
|
||||
- JSON-RPC по строкам достаточно или нужен бинарный протокол/shared memory.
|
||||
- MCP: отдельный процесс-адаптер или встроенный режим `fabrilis mcp`.
|
||||
- Права: что именно можно менять внешнему клиенту, а что только читать.
|
||||
- Частота управления по умолчанию и шаг децимации наблюдений.
|
||||
- Формат отчёта: CSV, JSON, RON или всё сразу.
|
||||
|
|
@ -4,7 +4,7 @@
|
|||
crate `tools/limits` (`fabrilis-limits`). У каждого crate'а есть `build.rs`, который
|
||||
вызывает его, поэтому **нарушение жёсткого правила ломает любую сборку**
|
||||
(`cargo build`, `check`, `clippy`, `test`). Весь репозиторий проверяется командой
|
||||
`cargo run -p fabrilis-limits`; она же стоит в pre-commit (`.githooks/`) и в CI.
|
||||
`cargo run -p fabrilis-limits`; она же стоит в pre-commit (`.githooks/`).
|
||||
|
||||
Правила касаются только нашего кода. `docs/`, `*.md` и `ref/` (локальные клоны
|
||||
чужих проектов, см. REFERENCES.md) не проверяются.
|
||||
|
|
@ -35,7 +35,7 @@ crate `tools/limits` (`fabrilis-limits`). У каждого crate'а есть `b
|
|||
быть длинным. Разносить тесты по подпапкам ради лимитов не нужно — весь модуль
|
||||
тестируется одним файлом рядом.
|
||||
|
||||
## Проверяют rustfmt и clippy (pre-commit и CI с `-D warnings`)
|
||||
## Проверяют rustfmt и clippy (pre-commit с `-D warnings`)
|
||||
|
||||
| Правило | Чем задано |
|
||||
|---|---|
|
||||
|
|
@ -90,6 +90,41 @@ crate `tools/limits` (`fabrilis-limits`). У каждого crate'а есть `b
|
|||
где это разумно).
|
||||
- Архитектурное изменение сопровождается записью в `DECISIONS.md`.
|
||||
|
||||
## Логирование (обязательно с первого дня)
|
||||
|
||||
Код пишет диагностику сразу, а не «потом добавим». Единая точка — фасад
|
||||
`fabrilis_core::log` с уровнями; приложение ставит приёмник (stderr, файл, dev-лог).
|
||||
`println!`/`eprintln!` в библиотечном коде запрещены: только `main` для `--help` и
|
||||
ошибок запуска.
|
||||
|
||||
| Уровень | Когда | Пример |
|
||||
|---|---|---|
|
||||
| `error` | работать дальше нельзя | не создался GPU-девайс, не загрузился проект |
|
||||
| `warn` | работаем, но деградация | шейдер не поддержан, шаг не сошёлся, поле не распознано |
|
||||
| `info` | жизненный цикл, один раз на событие | старт, seed и размер мира, загружено N деталей, режим |
|
||||
| `debug` | сводки и важные изменения | раз в секунду FPS/TPS/RTF, смена камеры, решение сходимости |
|
||||
| `trace` | покадрово/пошагово, только для разбора | входные события, каждый шаг решателя, пики контактов |
|
||||
|
||||
Правила:
|
||||
|
||||
- Уровень выбирается по смыслу события, а не по желанию. Горячий цикл логирует
|
||||
только `trace` и только после проверки уровня: строка не должна строиться, если
|
||||
уровень выключен.
|
||||
- Логи не влияют на симуляцию: логгер не меняет порядок, состояние и время.
|
||||
В crate'ах симуляции по-прежнему нет `Instant::now`/`SystemTime::now`; время для
|
||||
логов ставит приёмник в `app`.
|
||||
- Пишем факты в виде `key=value`, а не склейку предложений: `frame=120
|
||||
frame_ms=18.4 physics_max_ms=0.6 trigger=contact`.
|
||||
- Ошибки и деградации логируются там, где возникли, а не только наверху.
|
||||
- Не логировать секреты и личные пути; большие буферы и меши не дампить.
|
||||
- Сообщения на английском (как комментарии), уровни и поля — стабильные.
|
||||
- Тесты: формат строки, парсеры, поведение выключенного уровня (строка не
|
||||
форматируется), неизменность golden-хеша при включённых логах.
|
||||
|
||||
`log`/`tracing` сейчас не берём: нужен свой минимальный фасад без зависимостей и с
|
||||
контролем детерминизма (D35). Если понадобится экосистема, заменим фасад, не меняя
|
||||
места вызовов.
|
||||
|
||||
## Идеи на потом (пока не включены)
|
||||
Каждый пункт можно включить отдельным шагом, когда проект дорастёт.
|
||||
|
||||
|
|
@ -102,7 +137,7 @@ crate `tools/limits` (`fabrilis-limits`). У каждого crate'а есть `b
|
|||
| `float_cmp`: сравнение `f64` через допуск, а не `==` | корректная численная логика |
|
||||
| Фаззинг (`cargo-fuzz`) для импорта мешей, форматов RON, декодера RISC-V | парсеры устойчивы к мусору |
|
||||
| Мутационное тестирование (`cargo-mutants`) и покрытие (`cargo-llvm-cov`) для `core`, `analog`, `cpu` | тесты реально ловят ошибки |
|
||||
| Порог регрессии бенчмарков в CI (своя утилита замеров) | скорость не падает незаметно |
|
||||
| Порог регрессии бенчмарков в автоматическом прогоне (своя утилита замеров) | скорость не падает незаметно |
|
||||
| Conventional Commits и `commit-msg` хук | читаемая история |
|
||||
| Проверка, что каждый crate описан в `ARCHITECTURE.md` | документация не отстаёт |
|
||||
| Лимит на число `unsafe`-блоков и место (только `cpu`, с обоснованием) | контроль рисков |
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
| # | Решение | Почему |
|
||||
|---|---|---|
|
||||
| D1 | Multi-crate workspace, симуляция без GPU/Bevy | тесты без окна, CI, детерминизм |
|
||||
| D1 | Multi-crate workspace, симуляция без GPU/Bevy | тесты без окна, автоматические прогоны, детерминизм |
|
||||
| D2 | Без Bevy; свой рендер на wgpu (Vulkan); без общего ECS, данные SoA внутри crate'ов | RX 470 слабая, нужен контроль; рендер заменяем |
|
||||
| D3 | Физика: гибрид. `PhysicsBackend` + `rapier3d-f64` с `enhanced-determinism` на старте, нужное заменяем своим | быстрый старт без потери контроля и без границы f32 |
|
||||
| D4 | Механика: жёсткие тела + нагрузки на шарниры (World); балки и FEM (Lab); разрушение | точность там, где нужна |
|
||||
|
|
@ -34,8 +34,10 @@
|
|||
| D30 | Проект публичный, но до 0.6.0 API плагинов и форматов нестабилен; обратная совместимость не обещается | ещё рано замораживать интерфейсы, а публичность задаёт планку документации |
|
||||
| D31 | Углы — newtype `Radians`; градусы только в интерфейсе и при импорте | градусы и радианы иначе путаются молча |
|
||||
| D32 | Очередь событий с метками в нс в планировщике: событие делит шаг подсистемы | фронты PWM и прерывания нельзя привязывать к эпохам |
|
||||
| D33 | Версия компилятора зафиксирована `rust-toolchain.toml`; CI собирает базовую и `native` сборки и сверяет хеши | разные LLVM могут разойтись в последних битах |
|
||||
| D33 | Версия компилятора зафиксирована `rust-toolchain.toml`; автоматический прогон собирает базовую и `native` сборки и сверяет хеши | разные LLVM могут разойтись в последних битах |
|
||||
| D34 | UI — свой immediate-mode слой на нашем `wgpu`-рендере с event-driven redraw; retained-дерево только по профилировке. ShapeUI blueprint — источник контрактов, не фундамент | редактору нужны панели, дерево и графики, а не окна произвольной формы; UI-фреймворк на годы остановил бы проект |
|
||||
| D35 | Логи — собственный фасад `core::log` с уровнями error/warn/info/debug/trace; приложение ставит приёмник, `--dev` включает debug/trace; логи не влияют на симуляцию | единый способ писать диагностику с первого дня, без внешних зависимостей и без влияния на детерминизм; `log`/`tracing` можно подключить позже |
|
||||
| D36 | Headless CLI — пульт управления движком и расчётный инструмент, отдельным бинарником без `render`/`ui`/`winit`; общий прогон мира живёт в `modes`. Внешние скрипты, агенты и нейросети управляют командами (JSON-RPC, позже MCP), логика остаётся снаружи | один протокол для прогонов, сервера и агентов; движок остаётся симулятором, а не чужим рантаймом |
|
||||
|
||||
## Открытые вопросы
|
||||
- FEM: тетраэдры для всей детали или балки + локальные тетраэдры в узлах.
|
||||
|
|
@ -46,6 +48,8 @@
|
|||
- Коллизии: `parry` оставляем навсегда или пишем свой узкий слой после своего
|
||||
физического backend'а.
|
||||
- Когда переходить с `wgpu` на `ash` (D24): после M4 по времени сборки и RTF.
|
||||
- Сетевой режим: транспорт (TCP или сразу QUIC), частота снапшотов, нужен ли
|
||||
предсказанный ввод; см. NETWORK.md.
|
||||
- Shaping и IME для текстовых полей: `cosmic-text` или `Parley`; решаем на M10.
|
||||
- Нужен ли retained-слой UI: решаем по профилировке M10.
|
||||
- Конкретная целевая плата и список реальных компонентов.
|
||||
|
|
|
|||
|
|
@ -7,8 +7,8 @@
|
|||
| Уровень | Что гарантирует | Где проверяется |
|
||||
|---|---|---|
|
||||
| **D1** | Повтор на той же машине, той же сборке, том же числе потоков даёт тот же результат | каждый коммит, golden-хеш |
|
||||
| **D2** | То же при любом числе потоков | CI, прогон с 1, 2, 8 и 24 потоками |
|
||||
| **D3** | Разные ОС и архитектуры (Linux x86-64, Windows, macOS ARM) дают одинаковый хеш | матрица CI, один хеш в репозитории |
|
||||
| **D2** | То же при любом числе потоков | автоматический прогон с 1, 2, 8 и 24 потоками |
|
||||
| **D3** | Разные ОС и архитектуры (Linux x86-64, Windows, macOS ARM) дают одинаковый хеш | прогон на трёх ОС, один хеш в репозитории |
|
||||
|
||||
D1 нужен для отладки, D2 — для параллельных развёрток, D3 — для «у меня не
|
||||
воспроизводится». Гарантия относится только к авторитетному состоянию симуляции;
|
||||
|
|
@ -36,7 +36,7 @@ D1 нужен для отладки, D2 — для параллельных ра
|
|||
9. **Векторы**: свои `Vec3`, `Mat3`, `Quat` в `core::vec` на `f64` через `core::math`
|
||||
(`glam` и `nalgebra` считают тригонометрию через системный libm).
|
||||
10. **Инструменты**: версия компилятора зафиксирована `rust-toolchain.toml`;
|
||||
авторитетная сборка идёт с базовым `target-cpu` (без `native`), CI дополнительно
|
||||
авторитетная сборка идёт с базовым `target-cpu` (без `native`), прогон дополнительно
|
||||
собирает с `native` и сверяет хеши.
|
||||
11. **SIMD**: только явные ядра с фиксированным порядком операций. Обычная
|
||||
автовекторизация допустима: она не меняет порядок сложений и не включает
|
||||
|
|
@ -53,7 +53,7 @@ D1 и D2 для конкретной сборки; хеши физических
|
|||
|
||||
## Проверка
|
||||
Golden-тест: хеш состояния после N тактов совпадает на Linux/Windows/macOS и при
|
||||
1, 2, 8 и 24 потоках. Хеш хранится в репозитории. При расхождении CI печатает
|
||||
1, 2, 8 и 24 потоках. Хеш хранится в репозитории. При расхождении прогон печатает
|
||||
первую подсистему, чей подснимок разошёлся (COUPLING.md).
|
||||
|
||||
## Адаптация под железо (`platform`)
|
||||
|
|
|
|||
93
docs/LOGGING.md
Normal file
93
docs/LOGGING.md
Normal file
|
|
@ -0,0 +1,93 @@
|
|||
# Логи и настройки
|
||||
|
||||
Диагностика не должна мешать симуляции: оверлей и логи — наблюдатели. Их включение
|
||||
не меняет шаг, порядок подсистем и результат (DETERMINISM.md). Время смотрят только
|
||||
`app` и логи; в симуляции по-прежнему `SimTime`.
|
||||
|
||||
Правила для кода — в [CODE_RULES.md](CODE_RULES.md), раздел «Логирование».
|
||||
|
||||
## Оверлей
|
||||
|
||||
Поверх кадра показывается панель (левый верхний угол выбран для M4d):
|
||||
|
||||
| Поле | Смысл |
|
||||
|---|---|
|
||||
| FPS | кадров в секунду за окно ~1 с |
|
||||
| TPS | шагов физики в секунду, реально выполненных |
|
||||
| frame ms | среднее и максимум времени кадра за окно |
|
||||
| physics ms | среднее и максимум времени шага/пачки шагов физики |
|
||||
| render ms | среднее время отрисовки |
|
||||
| RTF | simulated / wall, как в заголовке окна |
|
||||
| CPU | загрузка процесса, % одного ядра |
|
||||
| load1 | средняя нагрузка системы за 1 мин |
|
||||
| RSS | резидентная память процесса, МБ |
|
||||
|
||||
Под панелью — график времени кадра за последние ~180 кадров: линия кадра и линия
|
||||
физики, авто-масштаб по максимуму, сетка и подписи 0 / max мс. Пики контактов
|
||||
(переворот куба, удар) должны быть видны как узкие высокие всплески.
|
||||
|
||||
## Флаги запуска
|
||||
|
||||
| Флаг | Что делает |
|
||||
|---|---|
|
||||
| `--metrics-log <файл>` | писать метрики в CSV, по строке на кадр |
|
||||
| `--log <файл>` | писать dev-лог в указанный файл |
|
||||
| `--dev` | подробный режим: почти всё в dev-лог; включает метрики-лог, если путь не задан |
|
||||
| `--append` | дописывать в конец вместо перезаписи |
|
||||
|
||||
По умолчанию логи выключены. Файлы **перезаписываются при старте**; `--append`
|
||||
нужен только для накопления между запусками. Флаги командной строки важнее
|
||||
переменных окружения.
|
||||
|
||||
Переменные окружения: `FABRILIS_METRICS_LOG`, `FABRILIS_LOG`, `FABRILIS_DEV=1`.
|
||||
|
||||
## Метрики-лог (CSV)
|
||||
|
||||
Заголовок один раз, строка на кадр, сброс на диск раз в секунду:
|
||||
|
||||
```text
|
||||
unix_s,t_s,frame,fps,tps,frame_ms,frame_max_ms,physics_ms,physics_max_ms,render_ms,rtf,cpu_pct,load1,rss_mb,spike
|
||||
```
|
||||
|
||||
- `unix_s` — wall-clock начала кадра, секунды;
|
||||
- `t_s` — время симуляции, секунды;
|
||||
- `spike` — `1`, если кадр превысил бюджет (например, 20 мс) или шаг физики был
|
||||
дольше 1 мс;
|
||||
- остальные поля — как в оверлее.
|
||||
|
||||
CSV открывается таблицей, pandas и gnuplot. Приватных данных, кроме путей и имени
|
||||
GPU в dev-логе, нет.
|
||||
|
||||
## Dev-режим
|
||||
|
||||
`--dev` включает уровень `debug/trace` и пишет в текстовый лог:
|
||||
|
||||
- версии Rust/движка, ОС, адаптер GPU, драйвер, формат поверхности;
|
||||
- параметры окна, масштаб, размер буфера;
|
||||
- seed, конфигурацию и хеш рельефа;
|
||||
- созданные тела, коллайдеры, массы, стартовые позы;
|
||||
- параметры камеры и изменения управления (без покадрового шума);
|
||||
- раз в секунду — сводку метрик;
|
||||
- каждый пик: номер кадра, время кадра, время физики, причина (`contact`/`resize`/`render`);
|
||||
- ошибки wgpu/Rapier с контекстом.
|
||||
|
||||
Пик логируется отдельной строкой, поэтому «лаг в момент переворота» можно найти в
|
||||
логе, а не только на графике.
|
||||
|
||||
## Настройки (XDG, позже)
|
||||
|
||||
Постоянные личные настройки планируются отдельно от проекта (STORAGE.md):
|
||||
|
||||
```text
|
||||
~/.config/fabrilis/settings.ron
|
||||
```
|
||||
|
||||
Поля: `overlay`, `metrics_log`, `log`, `level`, `dev`. Пока достаточно флагов и
|
||||
переменных окружения; файл настроек добавим, когда появится UI настроек.
|
||||
|
||||
## Проверка
|
||||
|
||||
- Golden-хеш симуляции совпадает при включённом и выключенном оверлее/логе.
|
||||
- Парсеры `/proc/self/stat`, `/proc/loadavg`, `/proc/self/status` — чистые функции
|
||||
с тестами на битые строки (возвращают 0/None, не паникуют).
|
||||
- Метрики-лог не пишется, пока флаг не задан.
|
||||
68
docs/NETWORK.md
Normal file
68
docs/NETWORK.md
Normal file
|
|
@ -0,0 +1,68 @@
|
|||
# Сетевой режим (план)
|
||||
|
||||
Цель: физика может считаться не на машине зрителя. Один авторитетный сервер ведёт
|
||||
симуляцию, к нему подключаются клиенты: смотреть с разных углов, управлять, позже —
|
||||
редактировать. Текущая модульность это допускает: `core` уже даёт снимки и
|
||||
планировщик, `render` рисует по состоянию, `app` — точка сборки.
|
||||
|
||||
## Роли
|
||||
|
||||
| Роль | Что делает |
|
||||
|---|---|
|
||||
| **Server** | headless, авторитетная симуляция 1 кГц, снапшоты, приём ввода |
|
||||
| **Client** | окно, рендер, камера, отправка ввода, интерполяция между снапшотами |
|
||||
| **Observer** | клиент только на чтение: смотрит, не управляет |
|
||||
| **Editor** | позже: правки конструкции как команды серверу, не прямой доступ к состоянию |
|
||||
|
||||
## Модель
|
||||
|
||||
1. Сервер тикает фиксированным шагом и остаётся единственным источником истины.
|
||||
2. Клиенты **не симулируют авторитетное состояние**. Они получают снапшоты и
|
||||
интерполируют между двумя последними; рендер не влияет на сервер.
|
||||
3. Ввод идёт с номером последовательности; сервер применяет его на ближайшем шаге
|
||||
и подтверждает. Один клиент — владелец управления, остальные наблюдатели.
|
||||
4. Снапшот — уже существующий набор подснимков (COUPLING.md), сжатый и, позже,
|
||||
дельтами от базового. Частота снапшотов 20–60 Гц; шаг физики от неё не зависит.
|
||||
5. Для своего управления позже возможны предсказание и откат: только если
|
||||
детерминизм D1/D2 подтверждён, иначе клиент показывает подтверждённое состояние.
|
||||
|
||||
## Транспорт
|
||||
|
||||
Начинаем с TCP + собственный фрейминг (длина, версия, тип сообщения) на localhost и
|
||||
в LAN. QUIC/WebTransport — отдельное решение, когда понадобится интернет и
|
||||
мобильные клиенты. Формат сообщений версионируется как файлы (STORAGE.md);
|
||||
несовпадение версий — понятная ошибка, а не тихое расхождение.
|
||||
|
||||
## Что уже есть и чего не хватает
|
||||
|
||||
Есть: `Snapshot`/подснимки, `SimTime`, `Fidelity`, детерминированный планировщик,
|
||||
`render` по состоянию, слои crate'ов.
|
||||
Не хватает: сериализация снапшотов в сетевой формат, серверный бинарник без окна,
|
||||
клиентский цикл интерполяции, канал ввода, интерес-менеджмент по камере,
|
||||
аутентификация и права.
|
||||
|
||||
Серверная часть пересекается с [CLI.md](CLI.md): C5 — тот же headless-бинарник.
|
||||
|
||||
## Разрез работ
|
||||
|
||||
1. **S1 — headless-сервер.** Тот же мир без окна, тикает по часам, пишет метрики.
|
||||
2. **S2 — снапшоты по сети.** Один клиент подключается на localhost и рисует мир,
|
||||
полученный от сервера, без локальной физики.
|
||||
3. **S3 — несколько клиентов.** Два-три наблюдателя с разными камерами, сервер
|
||||
рассылает одно состояние; проверка, что картинки согласованы.
|
||||
4. **S4 — ввод.** Один клиент управляет телом, остальные видят результат;
|
||||
подтверждение ввода и отказ при разрыве.
|
||||
5. **S5 — интернет и устойчивость.** Сжатие, дельты, переподключение, лимиты,
|
||||
аутентификация по токену.
|
||||
|
||||
**DoD S3:** headless-сервер, два клиента на разных машинах/окнах, камеры независимы,
|
||||
состояние совпадает, разрыв одного клиента не роняет остальных.
|
||||
|
||||
## Открытые вопросы
|
||||
|
||||
- Транспорт: TCP сейчас или сразу QUIC.
|
||||
- Частота снапшотов и бюджет полосы на эталонной сцене.
|
||||
- Нужен ли предсказанный ввод или достаточно 50–100 мс задержки для наблюдения.
|
||||
- Кто владеет управлением: один клиент, очередь, или серверный сценарий.
|
||||
- Интерес-менеджмент: весь мир или только область вокруг камеры.
|
||||
- Где живёт сервер: отдельный бинарник `fabrilis-server` или подкоманда `app`.
|
||||
|
|
@ -14,6 +14,9 @@
|
|||
| [DECISIONS.md](DECISIONS.md) | принятые решения и открытые вопросы |
|
||||
| [MODES.md](MODES.md) | режимы Bench / Lab / World, Fidelity, время, события |
|
||||
| [UI.md](UI.md) | свой UI: модель, текст, event-driven redraw, что берём из ShapeUI |
|
||||
| [LOGGING.md](LOGGING.md) | оверлей метрик, CSV-лог, dev-режим, настройки |
|
||||
| [NETWORK.md](NETWORK.md) | сетевой режим: сервер физики, клиенты-наблюдатели |
|
||||
| [CLI.md](CLI.md) | headless CLI: прогоны, развёртки, сервер, среда для обучения |
|
||||
| [PHYSICS_SCOPE.md](PHYSICS_SCOPE.md) | механика, FEM, трение, тепло, вентиляция, проводка, виды |
|
||||
| [SCENARIOS.md](SCENARIOS.md) | сценарии, стабилизация, отказы, развёртки, метрики |
|
||||
| [ELECTRONICS.md](ELECTRONICS.md) | эмуляция CPU/SoC, аналоговая схема, мост |
|
||||
|
|
@ -34,6 +37,6 @@
|
|||
|
||||
Название: Fabrilis (лат. fabrilis, «относящийся к мастеру, ремесленнику»). Автор: loki.
|
||||
|
||||
Статус: готовы M0 (скелет, правила, CI) и M1 (ядро: единицы, время, математика,
|
||||
Статус: готовы M0 (скелет, правила) и M1 (ядро: единицы, время, математика,
|
||||
планировщик, Fidelity, снимки). Дальше M2 — один шарнир: своя векторная
|
||||
математика, seeded RNG, минимальная физика с мотором и датчиками.
|
||||
|
|
|
|||
|
|
@ -20,10 +20,10 @@
|
|||
6. **Форматы**: snapshot-тесты сцены и миграции версий; проверка меша до расчёта
|
||||
массы (замкнутость, ориентация нормалей, единицы).
|
||||
7. **Производительность**: бенчмарки горячих путей в `benches/` (`criterion` как
|
||||
dev-зависимость, D26) плюс бюджет эталонной сцены в CI; регрессия видна как
|
||||
dev-зависимость, D26) плюс бюджет эталонной сцены в автоматическом прогоне; регрессия видна как
|
||||
падение RTF.
|
||||
8. **Правила репозитория**: `fabrilis-limits` (в `build.rs` каждого crate'а,
|
||||
pre-commit и CI); тесты лежат в отдельных файлах (CODE_RULES.md).
|
||||
pre-commit); тесты лежат в отдельных файлах (CODE_RULES.md).
|
||||
9. **Сценарии Rhai** служат функциональными тестами («подними паука, замерь нагрузку»).
|
||||
|
||||
Verification (правильность реализации) и validation (совпадение с реальной
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue