NEOLearn

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.

Updated October 20, 2026

On this page

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#

PluginDiagnostics
FrameTimeDiagnosticsPluginFPS, FRAME_TIME (milliseconds) and FRAME_COUNT.
EntityCountDiagnosticsPluginENTITY_COUNT.
SystemInformationDiagnosticsPluginPROCESS_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::RenderDiagnosticsPluginTimings 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:

src/main.rs
use neo::diagnostic::{FrameTimeDiagnosticsPlugin, LogDiagnosticsPlugin};
use neo::prelude::*;

fn main() {
    App::new()
        .add_plugins((
            DefaultPlugins,
            FrameTimeDiagnosticsPlugin::default(),
            LogDiagnosticsPlugin::default(),
        ))
        .run();
}
LogDiagnosticsPlugin fieldWhat it does
wait_durationHow often it logs.
filterSome(set of DiagnosticPath) to log only those.
debugLogs 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:

Rust
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 methodReturns
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.

Rust
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.

Next steps#