Added kuniverse:PAUSE suffix and docs for it.

doc/source/structures/misc/kuniverse.rst

@@ -45,6 +45,10 @@ KUniverse 4th wall methods
           - :struct:`String`
           - Get
           - Returns the name of this vessel's editor, "SPH" or "VAB".
+        * - :meth:`PAUSE`
+          - None
+          - Method
+          - Pauses KSP, bringing up the "Escape Menu".
         * - :attr:`CANQUICKSAVE`
           - :struct:`Boolean`
           - Get
@@ -175,6 +179,36 @@ KUniverse 4th wall methods
     - "VAB" for things built in the vehicle assembly building.
     - "" (empty :struct:`String`) for cases where the vehicle cannot remember its editor (when KUniverse:CANREVERTTOEDITOR is false.)
 
+.. method:: KUniverse:PAUSE()
+
+    :access: Method
+    :type: None.
+
+    Pauses Kerbal Space Program, bringing up the same pause menu that would
+    normally appear when you hit the "Escape" key.
+
+    **Warning:** *NO lines of Kerboscript code can run while the game is
+    paused!!!  If you call this, you will be stopping your script there
+    until a human being clicks "resume" on the pause menu.*
+
+    kOS is designed to thematically act like a computer that lives *inside*
+    the game universe. That means it stops when the game clock stops, for
+    the same reason a bouncing ball stops when the game clock stops.
+
+    Until a human being resumes the game by clicking the Resume button
+    in the menu, your script will be stuck.  This makes it impossible
+    to have the program run code that decides when to un-pause the game.
+    Once the Resume button is clicked, then the program will
+    continue where it left off, just after the point where it called
+    ``KUniverse:PAUSE().``.
+
+    Note, if you use Control-C in the terminal to kill the program,
+    that *will* work while the game is paused like this.  If you make
+    the mistake of having your script keep re-pausing the game every
+    time the game resumes (i.e. you call ``Kuniverse:PAUSE()``
+    again and again in a loop), then using Control-C in the terminal
+    can be a way to break out of this problem.
+
 .. attribute:: KUniverse:CANQUICKSAVE
 
     :access: Get

src/kOS/Suffixed/KUniverseValue.cs

@@ -1,7 +1,8 @@
-using kOS.Safe.Compilation.KS;
+using kOS.Safe.Compilation.KS;
 using kOS.Safe.Encapsulation;
 using kOS.Safe.Encapsulation.Suffixes;
 using kOS.Safe.Exceptions;
+using kOS.Safe.Execution;
 using kOS.Safe.Utilities;
 using System;
 using System.IO;
@@ -30,6 +31,7 @@ public void InitializeSuffixes()
             AddSuffix("REVERTTOEDITOR", new NoArgsVoidSuffix(RevertToEditor));
             AddSuffix("REVERTTO", new OneArgsSuffix<StringValue>(RevertTo));
             AddSuffix("CANQUICKSAVE", new Suffix<BooleanValue>(CanQuicksave));
+            AddSuffix("PAUSE", new NoArgsVoidSuffix(PauseGame));
             AddSuffix("QUICKSAVE", new NoArgsVoidSuffix(QuickSave));
             AddSuffix("QUICKLOAD", new NoArgsVoidSuffix(QuickLoad));
             AddSuffix("QUICKSAVETO", new OneArgsSuffix<StringValue>(QuickSaveTo));
@@ -161,6 +163,19 @@ public BooleanValue CanQuicksave()
             return false;
         }
 
+        public void PauseGame()
+        {
+            string textToHud = "kOS script has triggered a Pause Game.  Manual intervention needed to resume.";
+            ScreenMessages.PostScreenMessage("<color=#ffff80><size=20>" + textToHud + "</size></color>", 10, ScreenMessageStyle.UPPER_CENTER);
+
+            PauseMenu.Display();
+
+            // It would be weird to execute the rest of the IPU's instructions when the script said to pause the game.
+            // Presumably most users would expect calling Pause to make the script stop right there, not
+            // like 3 or 4 lines later.  Therefore stop this FixedUpdate tick here:
+            shared.Cpu.YieldProgram(new YieldFinishedNextTick());
+        }
+
         public void QuickSave()
         {
             if (HighLogic.CurrentGame.Parameters.Flight.CanQuickSave)