concinnity_core/components/
engine_defaults.rs

1// Engine-injected default opt-out schema.
2
3/// Opts a world out of individual engine-injected defaults.
4///
5/// A world is completed at start with the standard components it does not
6/// declare itself: the [DebugHud](#debughud) with its chip
7/// [TextLabel](#textlabel)s and font, the chips and font of a
8/// [StatHud](#stathud), the [PhysicsConfig](#physicsconfig) a world with
9/// physics content simulates on, the [LoadingOverlay](#loadingoverlay) a
10/// streamed world waits behind, and, when an
11/// [EnvironmentMap](#environmentmap) is present, the sky mesh that displays
12/// it. Declaring a piece yourself keeps the injection from filling that slot;
13/// declaring `EngineDefaults` with a flag set to `false` removes the whole
14/// default.
15///
16/// Two defaults are stated in terms of a [MainMenu](#mainmenu), which the
17/// build expands away, so they are injected by the build instead: the
18/// `StatHud` a menu world drives, and a story world's pause menu.
19///
20/// ```rust
21/// # use concinnity_core::components::EngineDefaults;
22/// EngineDefaults {
23///     debug_hud: false,
24///     sky: false,
25///     ..Default::default()
26/// };
27/// ```
28#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
29#[serde(default)]
30pub struct EngineDefaults {
31    /// Inject the [StatHud](#stathud) when the world declares a
32    /// [MainMenu](#mainmenu) but no `StatHud`, and fill any declared
33    /// `StatHud`'s unset chip labels with chips.
34    pub hud: bool,
35    /// Inject the [DebugHud](#debughud) with its chip labels when the world
36    /// declares no `DebugHud`.
37    pub debug_hud: bool,
38    /// Inject the sky mesh (a skybox mesh, [Material](#material), and
39    /// [Prop](#prop)) when the world has an
40    /// [EnvironmentMap](#environmentmap) but no skybox mesh. Disable to use an
41    /// `EnvironmentMap` for image-based lighting only, with the background
42    /// left to `clear_color` or your own geometry.
43    pub sky: bool,
44    /// Inject an Escape-toggled pause [MainMenu](#mainmenu) when the world
45    /// plays a [Story](#story) but declares no `MainMenu`: Resume, Save, Load,
46    /// a trimmed Settings screen, and Quit to the story's title. Disable to
47    /// leave a story with no pause menu, or declare your own `MainMenu` to
48    /// replace it.
49    pub story_pause_menu: bool,
50    /// Inject the [LoadingOverlay](#loadingoverlay) with its screen, backdrop,
51    /// progress bar, and label when the world declares [Scene](#scene)s and a
52    /// [StreamingConfig](#streamingconfig) but no `LoadingOverlay`. Disable to
53    /// jump between scenes with no loading screen while their content streams
54    /// in.
55    pub loading_overlay: bool,
56    /// Inject a [PhysicsConfig](#physicsconfig) with the engine's own values
57    /// when the world has physics content -- a [RigidBody](#rigidbody), a
58    /// [PropBody](#propbody), a [TriggerVolume](#triggervolume), or a
59    /// [SkinnedMesh](#skinnedmesh) with a `capsule` -- but declares no
60    /// `PhysicsConfig`. Physics runs on those values either way; the injected
61    /// component is what makes them visible to tooling. Disable to leave them
62    /// implicit.
63    pub physics_config: bool,
64}
65
66impl Default for EngineDefaults {
67    fn default() -> Self {
68        Self {
69            hud: true,
70            debug_hud: true,
71            sky: true,
72            story_pause_menu: true,
73            loading_overlay: true,
74            physics_config: true,
75        }
76    }
77}
78
79#[cfg(test)]
80mod tests {
81    use super::*;
82
83    #[test]
84    fn every_injected_default_is_on_until_opted_out_of() {
85        // This component exists only to turn injection off, so declaring it
86        // without saying which one must change nothing.
87        let d = EngineDefaults::default();
88        assert!(d.hud);
89        assert!(d.debug_hud);
90        assert!(d.sky);
91        assert!(d.story_pause_menu);
92        assert!(d.loading_overlay);
93        assert!(d.physics_config);
94
95        let declared: EngineDefaults = serde_json::from_str("{}").unwrap();
96        assert_eq!(declared, EngineDefaults::default());
97    }
98
99    #[test]
100    fn opting_out_of_one_default_leaves_the_rest_alone() {
101        let d: EngineDefaults = serde_json::from_str(r#"{"sky":false}"#).unwrap();
102        assert!(!d.sky);
103        assert!(d.hud && d.debug_hud && d.story_pause_menu && d.loading_overlay);
104        assert!(d.physics_config);
105
106        let bytes = postcard::to_allocvec(&d).unwrap();
107        let back: EngineDefaults = postcard::from_bytes(&bytes).unwrap();
108        assert_eq!(back, d);
109    }
110}
concinnity_core/components/engine_defaults.rs

concinnity_core/components/
engine_defaults.rs
