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:
Loki 2026-11-16 23:34:05 +01:00
parent 878d144b77
commit 190ef9cc4b
111 changed files with 14801 additions and 63 deletions

View file

@ -0,0 +1,153 @@
//! Dev text log: wall-clock stamped lines with a level, a target and a message.
//!
//! The logger is a diagnostic observer. It is off unless `--dev`, `--log` or a
//! matching environment variable asks for it, and it never feeds data back into
//! the simulation.
//!
//! Line shape: `unix_s level target message`.
pub(crate) mod startup;
#[cfg(test)]
mod tests;
use std::fs::{File, OpenOptions};
use std::io::{self, Write};
use std::path::Path;
use std::time::{Instant, SystemTime, UNIX_EPOCH};
use crate::runtime::metrics::Stats;
/// How much detail the log records.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub(crate) enum Level {
Error,
Warn,
Info,
Debug,
#[allow(
dead_code,
reason = "trace belongs to the documented level set; --dev stops at debug"
)]
Trace,
}
impl Level {
/// Lower bounds `self`, so `self.rank() <= limit.rank()` means "log it".
fn rank(self) -> u8 {
match self {
Self::Error => 0,
Self::Warn => 1,
Self::Info => 2,
Self::Debug => 3,
Self::Trace => 4,
}
}
}
impl core::fmt::Display for Level {
fn fmt(&self, formatter: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
let name = match self {
Self::Error => "error",
Self::Warn => "warn",
Self::Info => "info",
Self::Debug => "debug",
Self::Trace => "trace",
};
formatter.write_str(name)
}
}
/// How often a metrics summary line is written, seconds.
const SUMMARY_INTERVAL_SECONDS: u64 = 1;
/// A dev log file, truncated or created when opened.
pub(crate) struct DevLog {
file: File,
level: Level,
last_summary: Instant,
}
impl DevLog {
/// Creates or opens the file, truncating it unless `append` is set, and
/// records `level` as the most detailed level to write.
#[allow(
clippy::disallowed_methods,
reason = "the dev log is a wall-clock observer of the app loop"
)]
pub(crate) fn open(path: &Path, level: Level, append: bool) -> io::Result<Self> {
let file = OpenOptions::new()
.create(true)
.write(true)
.append(append)
.truncate(!append)
.open(path)?;
Ok(Self {
file,
level,
last_summary: Instant::now(),
})
}
/// Writes one line and flushes it, so the log survives a crash.
pub(crate) fn write(&mut self, level: Level, target: &str, message: &str) -> io::Result<()> {
if level.rank() > self.level.rank() {
return Ok(());
}
let line = format_line(unix_now(), level, target, message);
writeln!(self.file, "{line}")?;
self.file.flush()
}
/// Whether the once-per-second metrics summary is due.
#[allow(
clippy::disallowed_methods,
reason = "the dev log is a wall-clock observer of the app loop"
)]
pub(crate) fn summary_due(&mut self) -> bool {
if self.last_summary.elapsed().as_secs() < SUMMARY_INTERVAL_SECONDS {
return false;
}
self.last_summary = Instant::now();
true
}
}
/// Formats one log line without the trailing newline.
pub(crate) fn format_line(unix_s: f64, level: Level, target: &str, message: &str) -> String {
format!("{unix_s:.3} {level} {target} {message}")
}
/// One-line metrics summary written about once per second.
pub(crate) fn summary(stats: &Stats) -> String {
format!(
"fps={:.1} tps={:.1} frame={:.2}/{:.2} ms physics={:.2}/{:.2} ms render={:.2} ms rtf={:.2} cpu={:.1}% load1={:.2} rss={:.1} MB",
stats.fps,
stats.tps,
stats.frame_avg_ms,
stats.frame_max_ms,
stats.physics_avg_ms,
stats.physics_max_ms,
stats.render_avg_ms,
stats.rtf,
stats.cpu_percent,
stats.load_1m,
stats.rss_mb,
)
}
/// One-line description of a frame that exceeded its budget.
pub(crate) fn spike(frame: u64, frame_ms: f32, step_ms: f32, trigger: &str) -> String {
format!("frame={frame} frame_ms={frame_ms:.2} physics_step_ms={step_ms:.3} trigger={trigger}")
}
/// Wall-clock seconds since the Unix epoch, as a float.
#[allow(
clippy::disallowed_methods,
reason = "the dev log is a wall-clock observer of the app loop"
)]
fn unix_now() -> f64 {
SystemTime::now()
.duration_since(UNIX_EPOCH)
.map_or(0.0, |elapsed| elapsed.as_secs_f64())
}