Struct bevy::diagnostic::Diagnostic

pub struct Diagnostic {
    pub suffix: Cow<'static, str>,
    pub is_enabled: bool,
    /* private fields */
}

A timeline of DiagnosticMeasurements of a specific type. Diagnostic examples: frames per second, CPU usage, network latency

Fields

suffix: Cow<'static, str>

is_enabled: bool

Implementations

impl Diagnostic

pub fn add_measurement(&mut self, measurement: DiagnosticMeasurement)

Add a new value as a DiagnosticMeasurement.

pub fn new(path: DiagnosticPath) -> Diagnostic

Create a new diagnostic with the given path.

Examples found in repository

examples/diagnostics/custom_diagnostic.rs (line 19)

fn main() {
    App::new()
        .add_plugins((
            DefaultPlugins,
            // The "print diagnostics" plugin is optional.
            // It just visualizes our diagnostics in the console.
            LogDiagnosticsPlugin::default(),
        ))
        // Diagnostics must be initialized before measurements can be added.
        .register_diagnostic(Diagnostic::new(SYSTEM_ITERATION_COUNT).with_suffix(" iterations"))
        .add_systems(Update, my_system)
        .run();
}

pub fn with_max_history_length(self, max_history_length: usize) -> Diagnostic

Set the maximum history length.

pub fn with_suffix(self, suffix: impl Into<Cow<'static, str>>) -> Diagnostic

Add a suffix to use when logging the value, can be used to show a unit.

Examples found in repository

examples/diagnostics/custom_diagnostic.rs (line 19)

fn main() {
    App::new()
        .add_plugins((
            DefaultPlugins,
            // The "print diagnostics" plugin is optional.
            // It just visualizes our diagnostics in the console.
            LogDiagnosticsPlugin::default(),
        ))
        // Diagnostics must be initialized before measurements can be added.
        .register_diagnostic(Diagnostic::new(SYSTEM_ITERATION_COUNT).with_suffix(" iterations"))
        .add_systems(Update, my_system)
        .run();
}

pub fn with_smoothing_factor(self, smoothing_factor: f64) -> Diagnostic

The smoothing factor used for the exponential smoothing used for smoothed.

If measurements come in less frequently than smoothing_factor seconds apart, no smoothing will be applied. As measurements come in more frequently, the smoothing takes a greater effect such that it takes approximately smoothing_factor seconds for 83% of an instantaneous change in measurement to e reflected in the smoothed value.

A smoothing factor of 0.0 will effectively disable smoothing.

pub fn path(&self) -> &DiagnosticPath

pub fn measurement(&self) -> Option<&DiagnosticMeasurement>

Get the latest measurement from this diagnostic.

pub fn value(&self) -> Option<f64>

Get the latest value from this diagnostic.

Examples found in repository

examples/stress_tests/bevymark.rs (line 532)

fn counter_system(
    diagnostics: Res<DiagnosticsStore>,
    counter: Res<BevyCounter>,
    mut query: Query<&mut Text, With<StatsText>>,
) {
    let mut text = query.single_mut();

    if counter.is_changed() {
        text.sections[1].value = counter.count.to_string();
    }

    if let Some(fps) = diagnostics.get(&FrameTimeDiagnosticsPlugin::FPS) {
        if let Some(raw) = fps.value() {
            text.sections[3].value = format!("{raw:.2}");
        }
        if let Some(sma) = fps.average() {
            text.sections[5].value = format!("{sma:.2}");
        }
        if let Some(ema) = fps.smoothed() {
            text.sections[7].value = format!("{ema:.2}");
        }
    };
}

pub fn average(&self) -> Option<f64>

Return the simple moving average of this diagnostic’s recent values. N.B. this a cheap operation as the sum is cached.

Examples found in repository

examples/stress_tests/bevymark.rs (line 535)

fn counter_system(
    diagnostics: Res<DiagnosticsStore>,
    counter: Res<BevyCounter>,
    mut query: Query<&mut Text, With<StatsText>>,
) {
    let mut text = query.single_mut();

    if counter.is_changed() {
        text.sections[1].value = counter.count.to_string();
    }

    if let Some(fps) = diagnostics.get(&FrameTimeDiagnosticsPlugin::FPS) {
        if let Some(raw) = fps.value() {
            text.sections[3].value = format!("{raw:.2}");
        }
        if let Some(sma) = fps.average() {
            text.sections[5].value = format!("{sma:.2}");
        }
        if let Some(ema) = fps.smoothed() {
            text.sections[7].value = format!("{ema:.2}");
        }
    };
}

pub fn smoothed(&self) -> Option<f64>

Return the exponential moving average of this diagnostic.

This is by default tuned to behave reasonably well for a typical measurement that changes every frame such as frametime. This can be adjusted using with_smoothing_factor.

Examples found in repository

examples/ui/text.rs (line 138)

fn text_update_system(
    diagnostics: Res<DiagnosticsStore>,
    mut query: Query<&mut Text, With<FpsText>>,
) {
    for mut text in &mut query {
        if let Some(fps) = diagnostics.get(&FrameTimeDiagnosticsPlugin::FPS) {
            if let Some(value) = fps.smoothed() {
                // Update the value of the second section
                text.sections[1].value = format!("{value:.2}");
            }
        }
    }
}

examples/stress_tests/many_gizmos.rs (line 104)

fn ui_system(mut query: Query<&mut Text>, config: Res<Config>, diag: Res<DiagnosticsStore>) {
    let mut text = query.single_mut();

    let Some(fps) = diag
        .get(&FrameTimeDiagnosticsPlugin::FPS)
        .and_then(|fps| fps.smoothed())
    else {
        return;
    };

    text.sections[0].value = format!(
        "Line count: {}\n\
        FPS: {:.0}\n\n\
        Controls:\n\
        Up/Down: Raise or lower the line count.\n\
        Spacebar: Toggle fancy mode.",
        config.line_count, fps,
    );
}

examples/stress_tests/bevymark.rs (line 538)

fn counter_system(
    diagnostics: Res<DiagnosticsStore>,
    counter: Res<BevyCounter>,
    mut query: Query<&mut Text, With<StatsText>>,
) {
    let mut text = query.single_mut();

    if counter.is_changed() {
        text.sections[1].value = counter.count.to_string();
    }

    if let Some(fps) = diagnostics.get(&FrameTimeDiagnosticsPlugin::FPS) {
        if let Some(raw) = fps.value() {
            text.sections[3].value = format!("{raw:.2}");
        }
        if let Some(sma) = fps.average() {
            text.sections[5].value = format!("{sma:.2}");
        }
        if let Some(ema) = fps.smoothed() {
            text.sections[7].value = format!("{ema:.2}");
        }
    };
}

examples/ui/text_debug.rs (line 202)

fn change_text_system(
    time: Res<Time>,
    diagnostics: Res<DiagnosticsStore>,
    mut query: Query<&mut Text, With<TextChanges>>,
) {
    for mut text in &mut query {
        let mut fps = 0.0;
        if let Some(fps_diagnostic) = diagnostics.get(&FrameTimeDiagnosticsPlugin::FPS) {
            if let Some(fps_smoothed) = fps_diagnostic.smoothed() {
                fps = fps_smoothed;
            }
        }

        let mut frame_time = time.delta_seconds_f64();
        if let Some(frame_time_diagnostic) =
            diagnostics.get(&FrameTimeDiagnosticsPlugin::FRAME_TIME)
        {
            if let Some(frame_time_smoothed) = frame_time_diagnostic.smoothed() {
                frame_time = frame_time_smoothed;
            }
        }

        text.sections[0].value = format!(
            "This text changes in the bottom right - {fps:.1} fps, {frame_time:.3} ms/frame",
        );

        text.sections[2].value = format!("{fps:.1}");

        text.sections[4].value = format!("{frame_time:.3}");
    }
}

pub fn history_len(&self) -> usize

Return the number of elements for this diagnostic.

pub fn duration(&self) -> Option<Duration>

Return the duration between the oldest and most recent values for this diagnostic.

pub fn get_max_history_length(&self) -> usize

Return the maximum number of elements for this diagnostic.

pub fn values(&self) -> impl Iterator<Item = &f64>

pub fn measurements(&self) -> impl Iterator<Item = &DiagnosticMeasurement>

pub fn clear_history(&mut self)

Clear the history of this diagnostic.

Trait Implementations

impl Debug for Diagnostic

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.