From ac4fd29899e2fed8cb53d771325994ed481eae6b Mon Sep 17 00:00:00 2001
From: "Somhairle H. Marisol" <muqiu-han@outlook.com>
Date: Mon, 21 Sep 2026 11:48:37 +0800
Subject: feat(desktop): P 键暂停帮助页
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

P 键改为打开暂停帮助页（完整键位说明），打开时暂停模拟并保留原控制状态，返回游戏时精确恢复（速度/暂停原状）；常驻 HUD 不放全键位清单。MenuState 新增 enterPauseHelp/exitPauseHelp 纯函数与回归测试。
---
 src/LivingVillage.Desktop.Tests/PrototypeTests.fs | 16 ++++++++++++++++
 src/LivingVillage.Desktop/Game.fs                 | 17 ++++++++++++++---
 src/LivingVillage.Desktop/MenuState.fs            | 10 ++++++++++
 3 files changed, 40 insertions(+), 3 deletions(-)

(limited to 'src')

diff --git a/src/LivingVillage.Desktop.Tests/PrototypeTests.fs b/src/LivingVillage.Desktop.Tests/PrototypeTests.fs
index f1f4aed..524573f 100644
--- a/src/LivingVillage.Desktop.Tests/PrototypeTests.fs
+++ b/src/LivingVillage.Desktop.Tests/PrototypeTests.fs
@@ -202,6 +202,22 @@ type PrototypeTests () =
         Assert.IsTrue(first.Tiles |> List.exists (fun tile -> tile.Kind = (VillageArt.RiverWater)))
         Assert.IsTrue(first.Tiles |> List.exists (fun tile -> tile.Kind = (VillageArt.StonePaving)))
 
+    [<TestMethod>]
+    member _.PauseHelpOpensFromPlayingAndRestoresSimulationControl () =
+        let original = { Paused = false; Speed = TwoX }
+        let state = { MenuState.create original true with Page = Playing }
+
+        let helpState, pausedControl = MenuState.enterPauseHelp original state
+        Assert.AreEqual<MenuPage>(Controls, helpState.Page)
+        Assert.AreEqual<MenuPage>(Playing, helpState.ReturnPage)
+        Assert.IsTrue(pausedControl.Paused)
+        Assert.AreEqual<SimulationSpeed>(TwoX, pausedControl.Speed)
+
+        let backState, restoredControl = MenuState.exitPauseHelp original helpState
+        Assert.AreEqual<MenuPage>(Playing, backState.Page)
+        Assert.IsFalse(restoredControl.Paused)
+        Assert.AreEqual<SimulationControl>(original, restoredControl)
+
     [<TestMethod>]
     member _.CornerStatusShowsDayMoneyAndEnergyFromRealData () =
         let world = Sim.initialWorldN 42UL 0
diff --git a/src/LivingVillage.Desktop/Game.fs b/src/LivingVillage.Desktop/Game.fs
index 785a6aa..9e229aa 100644
--- a/src/LivingVillage.Desktop/Game.fs
+++ b/src/LivingVillage.Desktop/Game.fs
@@ -145,6 +145,7 @@ type LivingVillageGame() as this =
     let mutable hudClock = 0L
     let mutable hudStatus = ""
     let mutable hudStatusAt = 0L
+    let mutable pauseHelpControl: SimulationControl option = None
 
     do
         graphics.PreferredBackBufferWidth <- 1280
@@ -280,9 +281,12 @@ type LivingVillageGame() as this =
         let lPressed = pressed Keys.L
         let escapePressed = pressed Keys.Escape
         if pressed Keys.P then
-            simulationControl <- SimulationControl.togglePause simulationControl
-            menu <- MenuState.setSettings simulationControl menu
-            printfn $"simulation={M6Presentation.clockLabel simulationControl}"
+            if m5View.Panel = WorldPanel then
+                let helpState, pausedControl = MenuState.enterPauseHelp simulationControl menu
+                menu <- helpState
+                pauseHelpControl <- Some simulationControl
+                simulationControl <- pausedControl
+                printfn $"help=pause-open simulation={M6Presentation.clockLabel simulationControl}"
         if pressed Keys.F1 then
             simulationControl <- SimulationControl.setSpeed OneX simulationControl
             legacyStepsPerFrame <- None
@@ -443,6 +447,13 @@ type LivingVillageGame() as this =
             this.UpdatePlaying gameTime kb pressed pressedAny
         else
             this.UpdateMenu pressed
+        match pauseHelpControl with
+        | Some original when menu.Page = Playing ->
+            let _, restoredControl = MenuState.exitPauseHelp original menu
+            simulationControl <- restoredControl
+            pauseHelpControl <- None
+            printfn $"help=pause-close simulation={M6Presentation.clockLabel simulationControl}"
+        | _ -> ()
         hudClock <- hudClock + 1L
         if m5View.Status <> hudStatus then
             hudStatus <- m5View.Status
diff --git a/src/LivingVillage.Desktop/MenuState.fs b/src/LivingVillage.Desktop/MenuState.fs
index 452d233..2848e22 100644
--- a/src/LivingVillage.Desktop/MenuState.fs
+++ b/src/LivingVillage.Desktop/MenuState.fs
@@ -153,6 +153,11 @@ module MenuState =
     let openControls (state: MenuState) : MenuState =
         { state with Page = Controls; Selected = 0; ReturnPage = state.Page; Error = None }
 
+    /// P key: open the full key list as a pause-help page. The simulation is paused while
+    /// the page is open; the caller keeps the previous control and restores it on exit.
+    let enterPauseHelp (control: SimulationControl) (state: MenuState) : MenuState * SimulationControl =
+        openControls state, { control with Paused = true }
+
     let showLoadError (message: string) (state: MenuState) : MenuState =
         { state with Page = LoadError; Selected = 0; ReturnPage = MainMenu; Error = Some message }
 
@@ -161,6 +166,11 @@ module MenuState =
         | Playing -> { state with Page = Playing; Selected = 0; Error = None }
         | _ -> openMain state
 
+    /// Leaving the pause-help page returns to the page it was opened from and restores
+    /// the exact simulation control the player had before.
+    let exitPauseHelp (original: SimulationControl) (state: MenuState) : MenuState * SimulationControl =
+        returnFromSubpage state, original
+
     let private confirmMain (state: MenuState) : MenuState * MenuCommand =
         match selectedItem state with
         | ContinueItem -> enterGame state, ContinueGame
-- 
cgit v1.2.3