Merge pull request #10392 from tetrapod00/interpolation-improve

Improve Physics Interpolation pages

Author: mhilbrunner

tutorials/physics/index.rst

@@ -20,5 +20,5 @@ Physics
    collision_shapes_2d
    collision_shapes_3d
    large_world_coordinates
-   troubleshooting_physics_issues
    interpolation/index
+   troubleshooting_physics_issues

tutorials/physics/interpolation/2d_and_3d_physics_interpolation.rst

@@ -17,8 +17,8 @@ Global versus local interpolation
 This has some implications:
 
 - In 3D, it is easy to turn interpolation on and off at the level of each ``Node``,
-  via the ``physics_interpolation_mode`` property in the Inspector, which can be
-  set to ``On``, ``Off``, or ``Inherited``.
+  via the :ref:`physics_interpolation_mode<class_Node_property_physics_interpolation_mode>`
+  property in the Inspector, which can be set to ``On``, ``Off``, or ``Inherited``.
 
 .. figure:: img/physics_interpolation_mode.webp
     :align: center
@@ -28,7 +28,7 @@ This has some implications:
   physics tick. In most cases this will not matter, but in some situations the
   interpolation can look slightly wrong.
 - In 2D, interpolated local transforms are passed down to children during
-  rendering. This means that if a parent is set to ``physics_interpolation_mode``
+  rendering. This means that if a parent has ``physics_interpolation_mode`` set to
   ``On``, but the child is set to ``Off``, the child will still be interpolated if
   the parent is moving. *Only the child's local transform is uninterpolated.*
   Controlling the on / off behavior of 2D nodes therefore requires a little more
@@ -64,6 +64,6 @@ recommended to convert to ``CPUParticles2D`` (but keep a backup of your
 Other
 -----
 
-- ``get_global_transform_interpolated()`` - this is currently only available for 3D.
-- ``MultiMeshes`` - these should be supported in both 2D and 3D.
+- ``get_global_transform_interpolated()`` is currently only available for 3D.
+- ``MultiMeshes`` are supported in both 2D and 3D.
 

tutorials/physics/interpolation/advanced_physics_interpolation.rst

@@ -76,8 +76,8 @@ What we really want to focus the camera on, is not the position of the target on
 the physics tick, but the *interpolated* position, i.e. the position at which the
 target will be rendered.
 
-We can do this using the :ref:`Spatial.get_global_transform_interpolated<class_Node3D_method_get_global_transform_interpolated>`
-function. This acts exactly like getting :ref:`Spatial.global_transform<class_Node3D_property_global_transform>`
+We can do this using the :ref:`Node3D.get_global_transform_interpolated<class_Node3D_method_get_global_transform_interpolated>`
+function. This acts exactly like getting :ref:`Node3D.global_transform<class_Node3D_property_global_transform>`
 but it gives you the *interpolated* transform (during a ``_process()`` call).
 
 .. important:: ``get_global_transform_interpolated()`` should only be used once or
@@ -142,8 +142,12 @@ and directly apply the mouse input to the camera rotation, rather than apply it
 Sometimes, especially with cameras, you will want to use a combination of
 interpolation and non-interpolation:
 
-* A first person camera may position the camera at a player location (perhaps using :ref:`Spatial.get_global_transform_interpolated<class_Node3D_method_get_global_transform_interpolated>`), but control the Camera rotation from mouse look *without* interpolation.
-* A third person camera may similarly determine the look at (target location) of the camera using :ref:`Spatial.get_global_transform_interpolated<class_Node3D_method_get_global_transform_interpolated>`, but position the camera using mouse look *without* interpolation.
+- A first person camera may position the camera at a player location (perhaps using
+  :ref:`Node3D.get_global_transform_interpolated<class_Node3D_method_get_global_transform_interpolated>`),
+  but control the Camera rotation from mouse look *without* interpolation.
+- A third person camera may similarly determine the look at (target location) of the camera using
+  :ref:`Node3D.get_global_transform_interpolated<class_Node3D_method_get_global_transform_interpolated>`,
+  but position the camera using mouse look *without* interpolation.
 
 There are many permutations and variations of camera types, but it should be clear
 that in many cases, disabling automatic physics interpolation and handling this

tutorials/physics/interpolation/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. _doc_physics_interpolation:
 
 Physics Interpolation

tutorials/physics/interpolation/physics_interpolation_introduction.rst

@@ -4,7 +4,7 @@ Introduction
 ============
 
 Physics ticks and rendered frames
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------------------------
 
 One key concept to understand in Godot is the distinction between physics ticks
 (sometimes referred to as iterations or physics frames), and rendered frames. The

tutorials/physics/interpolation/using_physics_interpolation.rst

@@ -11,9 +11,10 @@ games will work with few changes. That said there are some situations which requ
 special treatment, and these will be described.
 
 Turn on the physics interpolation setting
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-----------------------------------------
 
-The first step is to turn on physics interpolation in :ref:`ProjectSettings.physics/common/physics_interpolation<class_ProjectSettings_property_physics/common/physics_interpolation>`.
+The first step is to turn on physics interpolation in
+:ref:`Project Settings > Physics > Common > Physics Interpolation<class_ProjectSettings_property_physics/common/physics_interpolation>`
 You can now run your game.
 
 It is likely that nothing looks hugely different, particularly if you are running
@@ -23,11 +24,12 @@ behind the scenes.
 .. tip::
 
     To convert an existing game to use interpolation, it is highly recommended that
-    you temporarily set :ref:`ProjectSettings.physics/common/physics_ticks_per_second<class_ProjectSettings_property_physics/common/physics_ticks_per_second>`
-    to a low value such as 10, which will make interpolation problems more obvious.
+    you temporarily set
+    :ref:`Project Settings > Physics > Common > Physics Tick per Second<class_ProjectSettings_property_physics/common/physics_ticks_per_second>`
+    to a low value such as ``10``, which will make interpolation problems more obvious.
 
 Move (almost) all game logic from _process to _physics_process
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+--------------------------------------------------------------
 
 The most fundamental requirement for physics interpolation (which you may be doing
 already) is that you should be moving and performing game logic on your objects
@@ -57,9 +59,9 @@ longer run on every rendered frame.
 
 
 Ensure that all indirect movement happens during physics ticks
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+--------------------------------------------------------------
 
-Consider that in Godot, Nodes can be moved not just directly in your own scripts,
+Consider that in Godot, nodes can be moved not just directly in your own scripts,
 but also by automatic methods such as tweening, animation, and navigation. All
 these methods should also have their timing set to operate on the physics tick
 rather than each frame ("idle"), **if** you are using them to move objects (*these
@@ -70,7 +72,7 @@ methods can also be used to control properties that are not interpolated*).
           movement of parents should therefore also only occur during physics ticks.
 
 Choose a physics tick rate
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+--------------------------
 
 When using physics interpolation, the rendering is decoupled from physics, and you
 can choose any value that makes sense for your game. You are no longer limited to
@@ -91,7 +93,7 @@ As a rough guide:
           changing the project setting.
 
 Call ``reset_physics_interpolation()`` when teleporting objects
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------------------------------------------------------
 
 Most of the time, interpolation is what you want between two physics ticks.
 However, there is one situation in which it may *not* be what you want. That is