concinnity_core/components/
stat_hud.rs

1// Stats HUD schema.
2
3use crate::ecs::asset_id::AssetId;
4use crate::ecs::asset_id::de_opt_asset_ref;
5
6/// Requests the default on-screen stats HUD. Drives a set of
7/// [TextLabel](#textlabel) chips with live engine stats, refreshed on a fixed
8/// interval.
9///
10/// Each label field, when set, receives one chip: `fps_label` the averaged
11/// frame rate, `vram_label` the GPU-memory use, `ram_label` the host process
12/// memory (resident set size, against the memory budget when known), `ev_label`
13/// the auto-exposure value, and `edr_label` the HDR headroom multiplier. Chips
14/// whose stat is unavailable stay blank. The frame-rate and GPU-memory chips
15/// are shown or hidden from the in-game video settings ("Display performance
16/// stats"); the host-memory, exposure, and HDR chips show whenever their
17/// reading is available.
18///
19/// The chips are packed into a tight strip anchored at the top-left of the
20/// window, left to right in the order fps, vram, ram, ev, edr; a blank chip
21/// reserves no width, so hidden readouts leave no gap. Their on-screen position
22/// is fixed by the engine rather than the authored coordinates.
23///
24/// Developer-facing readouts (per-pass GPU timings, cursor position, live
25/// camera pose) live on the separate [DebugHud](#debughud), toggled with F1.
26///
27/// A world that declares a [MainMenu](#mainmenu) receives a `StatHud` from the
28/// build when it declares none, since the menu's performance-stats toggles
29/// drive the chips, and any label field left unset receives a chip at start.
30/// So the example below is only needed to restyle the chips or run a HUD
31/// without a menu. Declare an [EngineDefaults](#enginedefaults) with
32/// `"hud": false` to leave the chips unfilled.
33#[derive(Debug, Clone, Default, serde::Serialize, serde::Deserialize)]
34#[serde(default)]
35pub struct StatHud {
36    /// [TextLabel](#textlabel) that receives the frame-rate chip text.
37    #[serde(deserialize_with = "de_opt_asset_ref")]
38    pub fps_label: Option<AssetId>,
39    /// [TextLabel](#textlabel) that receives the GPU-memory chip text.
40    #[serde(deserialize_with = "de_opt_asset_ref")]
41    pub vram_label: Option<AssetId>,
42    /// [TextLabel](#textlabel) that receives the host-memory (RSS) chip text.
43    #[serde(deserialize_with = "de_opt_asset_ref")]
44    pub ram_label: Option<AssetId>,
45    /// [TextLabel](#textlabel) that receives the auto-exposure chip text.
46    #[serde(deserialize_with = "de_opt_asset_ref")]
47    pub ev_label: Option<AssetId>,
48    /// [TextLabel](#textlabel) that receives the HDR-headroom chip text.
49    #[serde(deserialize_with = "de_opt_asset_ref")]
50    pub edr_label: Option<AssetId>,
51}
52
53#[cfg(test)]
54mod tests {
55    use super::*;
56
57    #[test]
58    fn a_blank_hud_claims_no_labels() {
59        // Each chip is opt-in, so an unset slot suppresses that readout instead
60        // of drawing it somewhere arbitrary.
61        let h = StatHud::default();
62        assert!(h.fps_label.is_none());
63        assert!(h.vram_label.is_none());
64        assert!(h.ram_label.is_none());
65        assert!(h.ev_label.is_none());
66        assert!(h.edr_label.is_none());
67    }
68
69    #[test]
70    fn each_chip_binds_its_own_label_and_round_trips_through_postcard() {
71        crate::test_support::install_resolvers();
72        let h: StatHud = serde_json::from_str(
73            r#"{"fps_label":"fps_chip","vram_label":"vram","ram_label":"","ev_label":3,
74                "edr_label":"edr_chip"}"#,
75        )
76        .unwrap();
77        assert_eq!(h.fps_label, Some(AssetId(8)));
78        assert_eq!(h.vram_label, Some(AssetId(4)));
79        assert_eq!(h.ram_label, None);
80        assert_eq!(h.ev_label, Some(AssetId(3)));
81        assert_eq!(h.edr_label, Some(AssetId(8)));
82
83        let bytes = postcard::to_allocvec(&h).unwrap();
84        let back: StatHud = postcard::from_bytes(&bytes).unwrap();
85        assert_eq!(back.fps_label, Some(AssetId(8)));
86        assert_eq!(back.ram_label, None);
87        assert_eq!(back.ev_label, Some(AssetId(3)));
88    }
89}
concinnity_core/components/stat_hud.rs

concinnity_core/components/
stat_hud.rs
