0.1.0-0-pre.11-fix.5

crates/engines/engine-v1-common/src/game_loop.rs

@@ -1,11 +1,19 @@
 // file: crates/engines/engine-v1-common/src/game_loop.rs
-// version: 3
+// version: 4
 
 /// Minimal update contract implemented by a game state consumed by engine V1.
 pub trait EngineGame {
     /// Advances the game by one engine update using platform-independent input.
     fn update(&mut self, frame: crate::EngineFrame, input: crate::InputState);
 
+    /// Handles a platform-independent request to leave the current runtime.
+    ///
+    /// Games may mutate their state and return [`crate::QuitDecision::Continue`] to implement
+    /// pause/confirmation screens, navigation, score submission, saving, or other workflows.
+    fn quit_requested(&mut self, _request: crate::QuitRequest) -> crate::QuitDecision {
+        return crate::QuitDecision::Exit;
+    }
+
     /// Produces the platform-independent scene rendered after the update.
     fn scene(&self) -> crate::EngineScene {
         return crate::EngineScene::empty(crate::RenderColor::rgb(18, 18, 24));

crates/engines/engine-v1-common/src/lib.rs

@@ -1,5 +1,5 @@
 // file: crates/engines/engine-v1-common/src/lib.rs
-// version: 4
+// version: 5
 
 #![warn(missing_docs)]
 #![deny(unreachable_pub)]
@@ -12,6 +12,7 @@ mod frame;
 mod game_loop;
 mod input;
 mod pointer;
+mod quit;
 mod render;
 
 /// Re-export of the canonical logical input action used by engine V1 games.
@@ -26,6 +27,12 @@ pub use self::game_loop::FixedStepRunner;
 pub use self::input::InputState;
 /// Re-export of the normalized primary pointer snapshot.
 pub use self::pointer::PointerState;
+/// Re-export of a game's response to a quit request.
+pub use self::quit::QuitDecision;
+/// Re-export of the platform-independent quit request.
+pub use self::quit::QuitRequest;
+/// Re-export of the platform-level source of a quit request.
+pub use self::quit::QuitSource;
 /// Re-export of the maximum engine scene rectangle capacity.
 pub use self::render::ENGINE_SCENE_RECT_CAPACITY;
 /// Re-export of the platform-independent scene snapshot.

crates/engines/engine-v1-common/src/quit.rs

@@ -0,0 +1,42 @@
+// file: crates/engines/engine-v1-common/src/quit.rs
+// version: 1
+
+/// Origin of a platform-independent request to leave the current game runtime.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum QuitSource {
+    /// The operating-system or window manager requested the window to close.
+    WindowClose,
+    /// The Desktop Escape key requested leaving the runtime.
+    Escape,
+    /// The platform-native Back action requested leaving the runtime.
+    PlatformBack,
+}
+
+/// Decision returned by a game when the runtime requests to leave.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum QuitDecision {
+    /// Leave the current runtime immediately.
+    Exit,
+    /// Keep the runtime active after the game handled the request.
+    Continue,
+}
+
+/// Platform-independent quit request delivered to a game.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct QuitRequest {
+    source: QuitSource,
+}
+
+impl QuitRequest {
+    /// Creates a quit request from the supplied source.
+    #[must_use]
+    pub const fn new(source: QuitSource) -> Self {
+        return Self { source };
+    }
+
+    /// Returns the physical or platform-level source of the request.
+    #[must_use]
+    pub const fn source(self) -> QuitSource {
+        return self.source;
+    }
+}