Merge pull request #10359 from skyace65/PhysicsInterpolation

Port physics interpolation docs from 3.6

Author: mhilbrunner

tutorials/physics/index.rst

@@ -19,3 +19,4 @@ Physics
    collision_shapes_3d
    large_world_coordinates
    troubleshooting_physics_issues
+   interpolation/index

tutorials/physics/interpolation/2d_and_3d_physics_interpolation.rst

@@ -0,0 +1,69 @@
+.. _doc_2d_and_3d_physics_interpolation:
+
+2D and 3D physics interpolation
+===============================
+
+Generally 2D and 3D physics interpolation work in very similar ways. However, there
+are a few differences, which will be described here.
+
+Global versus local interpolation
+---------------------------------
+
+- In 3D, physics interpolation is performed *independently* on the **global
+  transform** of each 3D instance.
+- In 2D by contrast, physics interpolation is performed on the **local transform**
+  of each 2D instance.
+
+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``.
+
+.. figure:: img/physics_interpolation_mode.webp
+    :align: center
+
+- However this means that in 3D, pivots that occur in the ``SceneTree`` (due to
+  parent child relationships) can only be interpolated **approximately** over the
+  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``
+  ``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
+  thought and planning.
+- On the positive side, pivot behavior in the scene tree is perfectly preserved
+  during interpolation in 2D, which gives super smooth behaviour.
+
+Resetting physics interpolation
+-------------------------------
+
+Whenever objects are moved to a completely new position, and interpolation is not
+desired (so as to prevent a "streaking" artefact), it is the responsibility of the
+user to call ``reset_physics_interpolation()``.
+
+The good news is that in 2D, this is automatically done for you when nodes first
+enter the tree. This reduces boiler plate, and reduces the effort required to get
+an existing project working.
+
+.. note:: If you move objects *after* adding to the scene tree, you will still need
+          to call ``reset_physics_interpolation()`` as with 3D.
+
+2D Particles
+------------
+
+Currently only ``CPUParticles2D`` are supported for physics interpolation in 2D. It
+is recommended to use a physics tick rate of at least 20-30 ticks per second to
+keep particles looking fluid.
+
+``Particles2D`` (GPU particles) are not yet interpolated, so for now it is
+recommended to convert to ``CPUParticles2D`` (but keep a backup of your
+``Particles2D`` in case we get these working).
+
+Other
+-----
+
+- ``get_global_transform_interpolated()`` - this is currently only available for 3D.
+- ``MultiMeshes`` - these should be supported in both 2D and 3D.
+

tutorials/physics/interpolation/advanced_physics_interpolation.rst

@@ -0,0 +1,174 @@
+.. _doc_advanced_physics_interpolation:
+
+Advanced physics interpolation
+==============================
+
+Although the previous instructions will give satisfactory results in a lot of games,
+in some cases you will want to go a stage further to get the best possible results
+and the smoothest possible experience.
+
+Exceptions to automatic physics interpolation
+---------------------------------------------
+
+Even with physics interpolation active, there may be some local situations where
+you would benefit from disabling automatic interpolation for a
+:ref:`Node<class_Node>` (or branch of the :ref:`SceneTree<class_SceneTree>`), and
+have the finer control of performing interpolation manually.
+
+This is possible using the :ref:`Node.physics_interpolation_mode<class_Node_property_physics_interpolation_mode>`
+property which is present in all Nodes. If you for example, turn off interpolation
+for a Node, the children will recursively also be affected (as they default to
+inheriting the parent setting). This means you can easily disable interpolation for
+an entire subscene.
+
+The most common situation where you may want to perform your own interpolation is
+Cameras.
+
+Cameras
+~~~~~~~
+
+In many cases, a :ref:`Camera3D<class_Camera3D>` can use automatic interpolation
+just like any other node. However, for best results, especially at low physics tick
+rates, it is recommended that you take a manual approach to camera interpolation.
+
+This is because viewers are very sensitive to camera movement. For instance, a
+Camera3D that realigns slightly every 1/10th of a second (at 10tps tick rate) will
+often be noticeable. You can get a much smoother result by moving the camera each
+frame in ``_process``, and following an interpolated target manually.
+
+Manual camera interpolation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Ensure the camera is using global coordinate space
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The very first step when performing manual camera interpolation is to make sure the
+Camera3D transform is specified in *global space* rather than inheriting the
+transform of a moving parent. This is because feedback can occur between the
+movement of a parent node of a Camera3D and the movement of the camera Node itself,
+which can mess up the interpolation.
+
+There are two ways of doing this:
+
+1) Move the Camera3D so it is independent on its own branch, rather than being a child of a moving object.
+
+.. image:: img/fti_camera_worldspace.webp
+
+2) Call :ref:`Node3D.top_level<class_Node3D_property_top_level>` and set this to ``true``, which will make the Camera ignore the transform of its parent.
+
+Typical example
+^^^^^^^^^^^^^^^
+
+A typical example of a custom approach is to use the ``look_at`` function in the
+Camera3D every frame in ``_process()`` to look at a target node (such as the player).
+
+But there is a problem. If we use the traditional ``get_global_transform()`` on a
+Camera3D "target" node, this transform will only focus the Camera3D on the target *at
+the current physics tick*. This is *not* what we want, as the camera will jump
+about on each physics tick as the target moves. Even though the camera may be
+updated each frame, this does not help give smooth motion if the *target* is only
+changing each physics tick.
+
+get_global_transform_interpolated()
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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>`
+but it gives you the *interpolated* transform (during a ``_process()`` call).
+
+.. important:: ``get_global_transform_interpolated()`` should only be used once or
+               twice for special cases such as cameras. It should **not** be used
+               all over the place in your code (both for performance reasons, and
+               to give correct gameplay).
+
+.. note:: Aside from exceptions like the camera, in most cases, your game logic
+          should be in ``_physics_process()``. In game logic you should be calling
+          ``get_global_transform()`` or ``get_transform()``, which will give the
+          current physics transform (in global or local space respectively), which
+          is usually what you will want for gameplay code.
+
+Example manual camera script
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Here is an example of a simple fixed camera which follows an interpolated target:
+
+.. code-block:: gdscript
+
+    extends Camera3D
+        
+    # Node that the camera will follow
+    var _target
+        
+    # We will smoothly lerp to follow the target
+    # rather than follow exactly
+    var _target_pos : Vector3 = Vector3()
+        
+    func _ready() -> void:
+        # Find the target node
+        _target = get_node("../Player")
+        
+        # Turn off automatic physics interpolation for the Camera3D,
+        # we will be doing this manually
+        set_physics_interpolation_mode(Node.PHYSICS_INTERPOLATION_MODE_OFF)
+        
+    func _process(delta: float) -> void:
+        # Find the current interpolated transform of the target
+        var tr : Transform = _target.get_global_transform_interpolated()
+        
+        # Provide some delayed smoothed lerping towards the target position 
+        _target_pos = lerp(_target_pos, tr.origin, min(delta, 1.0))
+        
+        # Fixed camera position, but it will follow the target
+        look_at(_target_pos, Vector3(0, 1, 0))
+
+Mouse look
+^^^^^^^^^^
+
+Mouse look is a very common way of controlling cameras. But there is a problem.
+Unlike keyboard input which can be sampled periodically on the physics tick, mouse
+move events can come in continuously. The camera will be expected to react and
+follow these mouse movements on the next frame, rather than waiting until the next
+physics tick.
+
+In this situation, it can be better to disable physics interpolation for the camera
+node (using :ref:`Node.physics_interpolation_mode<class_Node_property_physics_interpolation_mode>`)
+and directly apply the mouse input to the camera rotation, rather than apply it in
+``_physics_process``.
+
+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.
+
+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
+yourself can give a better result.
+
+Disabling interpolation on other nodes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Although cameras are the most common example, there are a number of cases when you
+may wish other nodes to control their own interpolation, or be non-interpolated.
+Consider for example, a player in a top view game whose rotation is controlled by
+mouse look. Disabling physics rotation allows the player rotation to match the
+mouse in real-time.
+
+
+MultiMeshes
+~~~~~~~~~~~
+
+Although most visual Nodes follow the single Node single visual instance paradigm,
+MultiMeshes can control several instances from the same Node. Therefore, they have
+some extra functions for controlling interpolation functionality on a
+*per-instance* basis. You should explore these functions if you are using
+interpolated MultiMeshes.
+
+- :ref:`MultiMesh.reset_instance_physics_interpolation<class_MultiMesh_method_reset_instance_physics_interpolation>`
+- :ref:`MultiMesh.set_buffer_interpolated<class_MultiMesh_method_set_buffer_interpolated>`
+
+Full details are in the :ref:`MultiMesh<class_MultiMesh>` documentation.

tutorials/physics/interpolation/img/fti_camera_worldspace.webp

@@ -0,0 +1,14 @@
+.. _doc_physics_interpolation:
+
+Physics Interpolation
+=====================
+
+.. toctree::
+   :maxdepth: 1
+   :name: toc-physics-interpolation
+
+   physics_interpolation_quick_start_guide
+   physics_interpolation_introduction
+   using_physics_interpolation
+   advanced_physics_interpolation
+   2d_and_3d_physics_interpolation