BGE physics: get/set linear and angular damping

This patch adds the following R/W properties and method to `KX_GameObject`:

  - `linearDamping`  -- get/set linear damping
  - `angluarDamping`  -- get/set angular damping
  - `setDamping(linear, angular)` -- set both simultaneously

These allow runtime changes to the same properties that are accessible at design time in Blender's UI via `game.damping` and `game.rotation_damping`. The names of the properties were chosen to mirror the internal names of the BGE physics engine, as these are (AFAIK) also the commonly used names in physics literature.

Reviewers: campbellbarton

Projects: #game_physics

Differential Revision: https://developer.blender.org/D936

1 files changed, 30 insertions, 0 deletions

diff --git a/doc/python_api/rst/bge_types/bge.types.KX_GameObject.rst b/doc/python_api/rst/bge_types/bge.types.KX_GameObject.rst
index a6d03dee1a1..09f48fb17d5 100644
--- a/doc/python_api/rst/bge_types/bge.types.KX_GameObject.rst
+++ b/doc/python_api/rst/bge_types/bge.types.KX_GameObject.rst
@@ -78,6 +78,27 @@ base class --- :class:`SCA_IObject`
 
          The object must have a physics controller for the mass to be applied, otherwise the mass value will be returned as 0.0.
 
+   .. attribute:: linearDamping
+
+      The object's linear damping, also known as translational damping. Can be set simultaneously with angular damping using the :py:meth:`setDamping` method.
+
+      :type: float between 0 and 1 inclusive.
+
+      .. note::
+
+         The object must have a physics controller for the linear damping to be applied, otherwise the value will be returned as 0.0.
+
+   .. attribute:: angularDamping
+
+      The object's angular damping, also known as rotationation damping. Can be set simultaneously with linear damping using the :py:meth:`setDamping` method.
+
+      :type: float between 0 and 1 inclusive.
+
+      .. note::
+
+         The object must have a physics controller for the angular damping to be applied, otherwise the value will be returned as 0.0.
+
+
    .. attribute:: linVelocityMin
 
       Enforces the object keeps moving at a minimum velocity.
@@ -580,6 +601,15 @@ base class --- :class:`SCA_IObject`
          * True: you get the "local" impulse ie: relative to local coordinates with object orientation.
       :type local: boolean
 
+   .. method:: setDamping(linear_damping, angular_damping)
+
+      Sets both the :py:attr:`linearDamping` and :py:attr:`angularDamping` simultaneously. This is more efficient than setting both properties individually.
+
+      :arg linear_damping: Linear ("translational") damping factor.
+      :type linear_damping: float ∈ [0, 1]
+      :arg angular_damping: Angular ("rotational") damping factor.
+      :type angular_damping: float ∈ [0, 1]
+
    .. method:: suspendDynamics()
 
       Suspends physics for this object.