Diagnostics
Measure frames per second, frame time, entity count, CPU and memory with the diagnostics plugins, log them, read them in your own UI, and add your own measurements.
A diagnostic is a named number the engine measures over time, such as frames per second, keeping a short history so you can read the current value, an average or a smoothed value. DefaultPlugins includes the store that holds them; you add the plugins for the measurements you want.
Built-in measurements#
| Plugin | Diagnostics |
|---|---|
FrameTimeDiagnosticsPlugin | FPS, FRAME_TIME (milliseconds) and FRAME_COUNT. |
EntityCountDiagnosticsPlugin | ENTITY_COUNT. |
SystemInformationDiagnosticsPlugin | PROCESS_CPU_USAGE, PROCESS_MEM_USAGE, SYSTEM_CPU_USAGE, SYSTEM_MEM_USAGE. Measured every so often, not every frame. Works on Windows, macOS, Linux and Android; does nothing on iOS and the web. |
neo::render::diagnostic::RenderDiagnosticsPlugin | Timings for render passes, CPU and GPU, where the device supports timestamps. Verbose. |
Each constant is on its plugin, for example FrameTimeDiagnosticsPlugin::FPS. All of them are in neo::diagnostic.
Logging them#
LogDiagnosticsPlugin prints every diagnostic to the log once a second:
use neo::diagnostic::{FrameTimeDiagnosticsPlugin, LogDiagnosticsPlugin};
use neo::prelude::*;
fn main() {
App::new()
.add_plugins((
DefaultPlugins,
FrameTimeDiagnosticsPlugin::default(),
LogDiagnosticsPlugin::default(),
))
.run();
}LogDiagnosticsPlugin field | What it does |
|---|---|
wait_duration | How often it logs. |
filter | Some(set of DiagnosticPath) to log only those. |
debug | Logs each diagnostic's full Debug form instead of the value and average. |
Add the diagnostics plugins after DefaultPlugins: they use its time plugin.
Reading them yourself#
DiagnosticsStore is a resource. Read a value for an in-game counter:
use neo::diagnostic::{DiagnosticsStore, FrameTimeDiagnosticsPlugin};
#[derive(Component)]
struct FpsText;
fn show_fps(store: Res<DiagnosticsStore>, mut text: Single<&mut Text, With<FpsText>>) {
if let Some(fps) = store
.get(&FrameTimeDiagnosticsPlugin::FPS)
.and_then(|d| d.smoothed())
{
text.0 = format!("{fps:.0} fps");
}
}Diagnostic method | Returns |
|---|---|
value() | The latest measurement. |
smoothed() | An exponentially smoothed value: steadier on screen. |
average() | The mean of the kept history. |
values(), measurements(), history_len() | The history itself. |
Set is_enabled to false on a diagnostic (through store.iter_mut() or get_mut) to stop measuring it.
Your own diagnostics#
Register a path once, then add measurements from a system with the Diagnostics parameter. The closure only runs while the diagnostic is enabled, so an expensive measurement costs nothing when it's off.
use neo::diagnostic::{Diagnostic, DiagnosticPath, Diagnostics, RegisterDiagnostic};
const ENEMIES: DiagnosticPath = DiagnosticPath::const_new("game/enemies");
fn main() {
App::new()
.add_plugins(DefaultPlugins)
.register_diagnostic(Diagnostic::new(ENEMIES).with_suffix(" enemies"))
.add_systems(Update, count_enemies)
.run();
}
fn count_enemies(mut diagnostics: Diagnostics, enemies: Query<(), With<Enemy>>) {
diagnostics.add_measurement(&ENEMIES, || enemies.iter().count() as f64);
}An on-screen FPS counter and frame-time graph come ready-made in the developer tools; see Developer tools.
Examples: cargo run --example log_diagnostics, custom_diagnostic and enabling_disabling_diagnostic.