Add design persistence, world rendering, metrics overlay and logs
Some checks failed
ci / check (macos-latest) (push) Has been cancelled
ci / check (ubuntu-latest) (push) Has been cancelled
ci / check (windows-latest) (push) Has been cancelled

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:
Loki 2026-11-16 23:34:05 +01:00
parent 79928b645b
commit 93075ab1fd
Signed by: boba
GPG key ID: 6CDE87BC9A778D97
107 changed files with 14785 additions and 46 deletions

93
docs/LOGGING.md Normal file
View 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, не паникуют).
- Метрики-лог не пишется, пока флаг не задан.