concinnity_core/components/
loading_overlay.rs

1// Scene-loading progress overlay schema.
2
3use crate::ecs::asset_id::AssetId;
4use crate::ecs::asset_id::de_opt_asset_ref;
5
6/// Requests the scene-loading overlay: a full-window backdrop with a progress
7/// bar, shown while a scene jump waits for its streamed content and faded out
8/// once the destination scene is fully resident.
9///
10/// The overlay is assembled from ordinary UI elements the fields reference: a
11/// [Screen](#screen) that hosts them, a backdrop [Sprite](#sprite) covering
12/// the canvas, a progress-bar track and fill [Sprite](#sprite) pair, and a
13/// [TextLabel](#textlabel) above the bar. Each frame the engine widens the
14/// fill to the destination scene's load progress and rewrites the label with
15/// the percentage; restyle any piece by declaring it yourself and pointing the
16/// overlay's field at it.
17///
18/// While the overlay's screen is up the world pauses and its render is
19/// skipped, exactly like an opaque menu, but streaming keeps running so the
20/// load it reports can finish. Scenes whose content is already resident jump
21/// without the overlay ever appearing.
22///
23/// Every rendering world that declares [Scene](#scene)s and a
24/// [StreamingConfig](#streamingconfig) receives a `LoadingOverlay` at start
25/// when it declares none, and any field left unset receives the piece it
26/// names, so the example below is only needed to restyle them. Declare an
27/// [EngineDefaults](#enginedefaults) with `"loading_overlay": false` to leave
28/// the world without one.
29#[derive(Debug, Clone, Default, serde::Serialize, serde::Deserialize)]
30#[serde(default)]
31pub struct LoadingOverlay {
32    /// [Screen](#screen) the overlay shows while a scene loads. Its
33    /// `pauses_world` (on by default) freezes the world beneath the overlay so
34    /// the destination scene starts fresh when revealed.
35    #[serde(deserialize_with = "de_opt_asset_ref")]
36    pub screen: Option<AssetId>,
37    /// Backdrop [Sprite](#sprite) covering the canvas. Its tint alpha is
38    /// animated to reveal the scene once loading completes; an opaque tint
39    /// hides the still-loading world completely.
40    #[serde(deserialize_with = "de_opt_asset_ref")]
41    pub backdrop: Option<AssetId>,
42    /// Progress-bar track [Sprite](#sprite); its width is the bar's full
43    /// extent the fill is measured against.
44    #[serde(deserialize_with = "de_opt_asset_ref")]
45    pub track: Option<AssetId>,
46    /// Progress-bar fill [Sprite](#sprite); the engine sets its width to the
47    /// track width times the destination scene's load progress each frame.
48    #[serde(deserialize_with = "de_opt_asset_ref")]
49    pub fill: Option<AssetId>,
50    /// [TextLabel](#textlabel) rewritten each frame with the load percentage.
51    #[serde(deserialize_with = "de_opt_asset_ref")]
52    pub label: Option<AssetId>,
53}
54
55#[cfg(test)]
56mod tests {
57    use super::*;
58
59    #[test]
60    fn a_blank_overlay_claims_no_pieces() {
61        let o = LoadingOverlay::default();
62        assert!(o.screen.is_none());
63        assert!(o.backdrop.is_none());
64        assert!(o.track.is_none());
65        assert!(o.fill.is_none());
66        assert!(o.label.is_none());
67    }
68
69    #[test]
70    fn each_piece_binds_its_own_asset_and_round_trips_through_postcard() {
71        crate::test_support::install_resolvers();
72        let o: LoadingOverlay = serde_json::from_str(
73            r#"{"screen":"load","backdrop":"dim","track":"bar_bg","fill":"bar","label":"pct"}"#,
74        )
75        .unwrap();
76        assert_eq!(o.screen, Some(AssetId(4)));
77        assert_eq!(o.backdrop, Some(AssetId(3)));
78        assert_eq!(o.track, Some(AssetId(6)));
79        assert_eq!(o.fill, Some(AssetId(3)));
80        assert_eq!(o.label, Some(AssetId(3)));
81
82        let bytes = postcard::to_allocvec(&o).unwrap();
83        let back: LoadingOverlay = postcard::from_bytes(&bytes).unwrap();
84        assert_eq!(back.track, Some(AssetId(6)));
85        assert_eq!(back.screen, Some(AssetId(4)));
86    }
87}
concinnity_core/components/loading_overlay.rs

concinnity_core/components/
loading_overlay.rs
