Improve pausing games documentation

tutorials/scripting/pausing_games.rst

@@ -1,25 +1,21 @@
 .. _doc_pausing_games:
 
-Pausing games
-=============
+Pausing games and process mode
+==============================
 
-Pause?
-------
+Introduction
+------------
 
 In most games it is desirable to, at some point, interrupt the
 game to do something else, such as taking a break or changing options.
-However, this is not as simple as it seems. The game might be stopped,
-but it might be desirable that some menus and animations continue
-working.
-
-Implementing a fine-grained control for what can be paused (and what can
-not) is a lot of work, so a simple framework for pausing is provided in
+Implementing a fine-grained control for what can be paused (and what cannot)
+is a lot of work, so a simple framework for pausing is provided in
 Godot.
 
 How pausing works
 -----------------
 
-To set pause mode, the pause state must be set. This is done by assigning
+To pause the game the pause state must be set. This is done by assigning
 ``true`` to the :ref:`SceneTree.paused <class_SceneTree_property_paused>` property:
 
 .. tabs::
@@ -31,27 +27,22 @@ To set pause mode, the pause state must be set. This is done by assigning
 
     GetTree().Paused = true;
 
-Doing so will have the following behavior:
-
--  2D and 3D physics will be stopped.
--  ``_process`` and ``_physics_process`` will not be called anymore in nodes.
--  ``_input`` and ``_input_event`` will not be called anymore either.
+Doing this will cause two things. First, 2D and 3D physics will be stopped
+for all nodes. Second, the behavior of certain nodes will stop or start
+depending on their process mode.
 
-This effectively stops the whole game. Calling this function from a
-script, by default, will result in an unrecoverable state (nothing will
-work anymore!).
+.. note:: The physics servers can be made active while the game is
+          paused by using their ``set_active`` methods.
 
-White-listing nodes
--------------------
+Process Modes
+-------------
 
-Before enabling pause, make sure that nodes that must keep working
-during pause are white-listed. This is done by editing the "Pause Mode"
-property in a node:
+Each node in Godot has a "Pause Mode" that defines when it processes. It can
+be found and changed under a node's :ref:`Node <class_Node>` properties in the inspector.
 
 .. image:: img/pausemode.png
 
-You can achieve the same result in code:
-
+You can also alter the property with code:
 
 .. tabs::
  .. code-tab:: gdscript GDScript
@@ -66,15 +57,7 @@ You can achieve the same result in code:
         PauseMode = Node.PauseModeEnum.Process;
     }
 
-By default, all nodes have this property in the "Inherit" state. This
-means, that they will only process (or not) depending on what this same
-property is set on the parent node. If the parent is set to "Inherit" ,
-then the grandparent will be checked and so on. Ultimately, if a state
-can't be found in any of the grandparents, the pause state in SceneTree
-is used. This means that, by default, when the game is paused every node
-will be paused.
-
-So the three possible states for a node are:
+This is what each mode tells a node to do:
 
 -  **Inherit**: Process depending on the state of the parent,
    grandparent, etc. The first parent that has a non-Inherit state.
@@ -83,17 +66,34 @@ So the three possible states for a node are:
 -  **Process**: Process the node no matter what (and children in Inherit
    mode). Paused or not this node will process.
 
-Example
--------
+By default, all nodes have this property in the "Inherit" state. If the
+parent is set to "Inherit", then the grandparent will be checked and so
+on. If a state can't be found in any of the grandparents, the pause state
+in SceneTree is used. This means that, by default, when the game is paused
+every node will be paused. Several things happen when a node stops processing.
 
-An example of this is creating a popup or panel with controls inside,
-and set its pause mode to "Process" then hide it:
+``_process``, ``_physics_process``, ``_input``, and ``_input_event`` functions
+will not be called". However signals still work and cause their connected function to
+run, even if that function's script is attached to a node that has its pause
+mode set to "Stop".
 
-.. image:: img/pause_popup.png
+animation nodes will pause their current animation, audio nodes
+will pause their current audio stream, and particles will pause. These resume
+automatically when the game is no longer paused.
 
-Just by setting the root of the pause popup to "Process", all children
-and grandchildren will inherit that state. This way, this branch of the
-scene tree will continue working when paused.
+It is important to note that even if a node is processing while the game is
+paused physics will **NOT** work for it by default. As stated earlier this is
+because the physics servers are turned off. The physics servers can be made
+active while the game is paused by using their ``set_active`` methods.
+
+Pause Menu Example
+------------------
+
+Here is an example of a pause menu. create a popup or panel with controls
+inside, and set its pause mode to "Process" then hide it. By setting the
+root of the pause popup to "Process", all children and grandchildren will
+inherit that state. This way, this branch of the scene tree will continue
+working when paused.
 
 Finally, make it so when a pause button is pressed (any button will do),
 enable the pause and show the pause screen.
@@ -130,5 +130,3 @@ closed:
         GetNode<Control>("pause_popup").Hide();
         GetTree().Paused = false;
     }
-
-And that should be all!