Fix incorrect PhyicsEnginePymunk doc and expand some stubs (#2216)

pushfoo · web-flow · commit 6988eff60aec · 2024-07-05T18:47:12.000-04:00
* Add intersphinx support for Pymunk

* Fix the PymunkPhysicsEngine.set_friction docstring

* Fix meaningless duplicated docstring

* Add link target to Pymunk engine tutorial file

* Add cross-references to set_friction

* Fix broken line reference for tmx loading of platforms

* Fix doc for the set_velocity function

* Correct incorrect doctsring for set_position

* Expand unclear get_sprite_for_shape docstring

* Document pymunk.Body type constant aliases

* Whitespace fixes

* Corrections to add_sprite doc

* Typo fix in cross-reference

* Improvements to add_sprite docstring

* Add some cross-refs

* Rework and cross-ref the top-level docstring of PymunkPhysicsEngine

* Fix cross-ref to PhysicsEnginePymunk

* Fix whitespace for ruff

* Fix whitespace issues in docstring

* Fix more typos

* Fix external links
diff --git a/arcade/physics_engines.py b/arcade/physics_engines.py
@@ -301,7 +301,8 @@ class PhysicsEngineSimple:
 
     For side-scrolling games focused on jumping puzzles, you may want
     the :py:class:`PlatformerPhysicsEngine` instead. Experienced users
-    may want to try the :py:class:`~arcade.pymunk_phyics_engine.PymunkPhysicsEngine`.
+    may want to try the
+    :py:class:`~arcade.pymunk_physics_engine.PymunkPhysicsEngine`.
 
     Args:
         player_sprite:
diff --git a/arcade/pymunk_physics_engine.py b/arcade/pymunk_physics_engine.py
@@ -37,19 +37,103 @@ class PymunkException(Exception):
 # Temp fix for https://github.com/pythonarcade/arcade/issues/2074
 @copy_dunders_unimplemented
 class PymunkPhysicsEngine:
-    """
-    Pymunk Physics Engine
+    """An Arcade-specific adapter for Pymunk.
+
+    .. _Pymunk: https://www.pymunk.org/en/latest/index.html
+    .. _Chipmunk2D:  https://chipmunk-physics.net/
+    .. _CONTRIBUTING.md: https://github.com/pythonarcade/arcade/blob/development/CONTRIBUTING.md
+
+    `Pymunk`_ is itself a Python adapter for the professional-grade
+    `Chipmunk2D`_ engine. However, Arcade's ``PymunkPhysicsEngine``
+    and its doc are currently in need of improvement.
+
+     .. note:: Arcade would welcome assistance with improving it.
+
+               If you are interested, please see Arcade's
+               `CONTRIBUTING.md`_.
+
+    Args:
+        gravity:
+            The direction where gravity is pointing.
+            See :py:attr:`pymunk.Space.gravity` to learn more.
+        damping:
+            The default velocity loss per tick across the
+            :py:class:`~pymunk.Space` for all :py:attr:`DYNAMIC`
+            objects.
+
+            * Override this for objects by passing different value
+              :`add_sprite` or :py:meth:`add_spritelist`
+            * See :py:attr:`pymunk.Space.damping` to learn more
+
+        maximum_incline_on_ground:
+            The maximum incline the ground can have before
+            :py:meth:`is_on_ground` returns ``False``.
+
+            * Defaults to ``0.708`` radians (a bit over 45 °)
+            * Not a pymunk value, but an Arcade feature
 
-    :param gravity: The direction where gravity is pointing
-    :param damping: The amount of speed which is kept to the next tick. A value of 1.0 means no speed loss,
-                    while 0.9 has 10% loss of speed etc.
-    :param maximum_incline_on_ground: The maximum incline the ground can have, before is_on_ground() becomes False
-        default = 0.708 or a little bit over 45° angle
     """
 
     DYNAMIC = pymunk.Body.DYNAMIC
+    """A ``body_type`` for moving Pymunk-controlled objects.
+
+    An indirect approach is best for controlling the velocity and
+    positioning of dynamic objects:
+
+    * :py:meth:`apply_force`
+    * :py:meth:`apply_impulse`
+
+    .. warning:: Avoid setting velocity directly on dynamic objects!
+
+                 If you need to set velocity directly, you may want to
+                 pass :py:attr:`KINEMATIC` as the ``body_type`` to
+                 :py:meth:`add_sprite` instead.
+
+    If you :py:class:`set_velocity` directly anyway, the
+    following may occur:
+
+    #. Setting velocity approaches infinite acceleration
+    #. ``f = m * a`` approaches ``f = m * infinity``
+    #. Collisions go haywire
+
+    In some games, you may be able to find a way to harness this for
+    comedic effect.
+
+    .. note:: This value is an alias of :py:attr:`pymunk.Body.DYNAMIC`.
+
+              Please see the Pymunk page linked above to learn more.
+    """
     STATIC = pymunk.Body.STATIC
+    """A ``body_type`` for objects which do not move.
+
+    This is best used for terrain or non-moving platforms.
+
+    .. note:: This value is an alias of :py:attr:`pymunk.Body.STATIC`.
+
+              Please see the Pymunk page linked above to learn more.
+    """
     KINEMATIC = pymunk.Body.KINEMATIC
+    """A ``body_type`` for objects controlled by your code or Arcade's.
+
+    When colliding, Kinematic objects:
+
+    * act as if they have infinite mass
+    * prevent joined and touching objects from sleeping
+
+    This makes them excellent for game elements like moving platforms or
+    hazards which move or crush game objects. You can control kinematic
+    objects by setting their positions and velocities directly:
+
+    * :py:meth:`set_velocity`
+    * :py:meth:`set_velocity_horizontal`
+    * :py:meth:`set_velocity_vertical`
+    * :py:meth:`set_position`
+
+
+    .. note:: This value is an alias of :py:attr:`pymunk.Body.KINEMATIC`.
+
+              Please see the Pymunk page linked above to learn more.
+    """
     MOMENT_INF = float("inf")
 
     def __init__(
@@ -67,7 +151,7 @@ def __init__(
     def add_sprite(
         self,
         sprite: Sprite,
-        mass: float = 1,
+        mass: float = 1.0,
         friction: float = 0.2,
         elasticity: Optional[float] = None,
         moment_of_inertia: Optional[float] = None,  # correct spelling
@@ -80,23 +164,72 @@ def add_sprite(
         radius: float = 0,
         collision_type: Optional[str] = "default",
     ):
-        """ Add a sprite to the physics engine.
-
-            :param sprite: The sprite to add.
-            :param mass: The mass of the object. Defaults to 1.
-            :param friction: The friction the object has. Defaults to 0.2.
-            :param elasticity: How bouncy this object is. 0 is no bounce. Values of 1.0 and higher may behave badly.
-            :param moment_of_inertia: The moment of inertia, or force needed to change angular momentum. \
-            Providing infinite makes this object stuck in its rotation.
-            :param body_type: The type of the body. Defaults to Dynamic, meaning, the body can move, rotate etc. \
-            Providing STATIC makes it fixed to the world.
-            :param damping: See class docs.
-            :param gravity: See class docs.
-            :param max_velocity: The maximum velocity of the object.
-            :param max_horizontal_velocity: Maximum velocity on the x axis in pixels.
-            :param max_vertical_velocity: Maximum velocity on the y axis in pixels.
-            :param radius: Radius for the shape created for the sprite in pixels.
-            :param collision_type: Assign a name to the sprite, use this name when adding collision handler.
+        """Add a sprite to the physics engine.
+
+        Args:
+            sprite:
+                A :py:class:`.Sprite` to add
+            mass:
+                The mass of the object (Defaults to ``1.0``).
+            friction:
+                How much the object resists sliding against surfaces:
+
+                .. list-table::
+                   :header-rows: 0
+
+                   * - ``0.0``
+                     - Absolutely slippery with no resistance at all
+                   * - ``0.2``
+                     - Default (Waxed wood on very wet snow)
+                   * - ``friction > 1.0``
+                     - Very rough
+
+                *Higher values may not make a meaningful difference.*
+
+                See :py:attr:`pymunk.Shape.friction` to learn more.
+
+            elasticity:
+                How bouncy the object is.
+
+                .. list-table::
+                   :header-rows: 0
+
+                   * - ``0.0``
+                     - No bounce
+                   * - ``0.99``
+                     - Very bouncy
+                   * - ``elasticity >= 1.0``
+                     - May behave badly (breaks conservation of energy)
+
+                See :py:attr:`pymunk.Shape.elasticity` to learn more.
+
+            moment_of_inertia:
+                How much force is needed to change the object's rotation (
+                pass :py:attr:`MOMENT_INF` or ``float('inf')`` to "lock"
+                its angle).
+
+                See :py:attr:`pymunk.Shape.moment_of_inertia` to learn more.
+
+            body_type:
+                :py:attr:`DYNAMIC` (default), :py:attr:`KINEMATIC`, or
+                :py:attr:`STATIC`.
+            damping:
+                Like air resistance. See the :py:class:`.PymunkPhysicsEngine`
+                top-level doc.
+            gravity:
+                See the :py:class:`.PymunkPhysicsEngine` top-level doc.
+            max_velocity:
+                The maximum velocity of this object.
+            max_horizontal_velocity:
+                Clamp the velocity on the x axis to this.
+            max_vertical_velocity:
+                Clamp the velocity along the y axis to this.
+            radius:
+                The radius for the :py:class:`pymunk.Shape` created for
+                the :py:class:`sprite <.Sprite>`.
+            collision_type:
+                Assign a collision name to this sprite. It will be used
+                by :py:meth:`add_collision_handler` if called.
         """
 
         if damping is not None:
@@ -228,7 +361,6 @@ def add_sprite_list(
         collision_type: Optional[str] = None,
     ):
         """Add all sprites in a sprite list to the physics engine."""
-
         for sprite in sprite_list:
             self.add_sprite(
                 sprite=sprite,
@@ -251,7 +383,22 @@ def remove_sprite(self, sprite: Sprite):
             self.non_static_sprite_list.remove(sprite)
 
     def get_sprite_for_shape(self, shape: Optional[pymunk.Shape]) -> Optional[Sprite]:
-        """Given a shape, what sprite is associated with it?"""
+        """Try to get the sprite registered with this engine for ``shape``.
+
+        This method returns ``None`` when:
+
+        * ``shape`` is ``None``
+        * No :py:class:`.Sprite` was to this engine for ``shape``
+
+        The second item may occur if you are using multiple instances of
+        :py:class:`.PymunkPhysicsEngine`.
+
+        Args:
+            shape:
+                A Pymunk shape to perform lookup for.
+        Returns:
+            A sprite for the ``shape``; ``None`` if no sprite is known.
+        """
         for sprite in self.sprites:
             if self.sprites[sprite].shape is shape:
                 return sprite
@@ -281,7 +428,16 @@ def apply_impulse(self, sprite: Sprite, impulse: tuple[float, float]):
         physics_object.body.apply_impulse_at_local_point(impulse)
 
     def set_position(self, sprite: Sprite, position: Union[pymunk.Vec2d, tuple[float, float]]):
-        """Apply an impulse force on a sprite"""
+        """Set the position of the sprite in the engine's simulation.
+
+        To learn more, please see :py:attr:`pymunk.Body.position`.
+
+        Args:
+            sprite:
+                An Arcade :py:class:`.Sprite` known to the engine.
+            position:
+                A two-dimensional position in world space.
+        """
         physics_object = self.get_physics_object(sprite)
         if physics_object.body is None:
             raise PymunkException(
@@ -298,7 +454,20 @@ def set_rotation(self, sprite: Sprite, rotation: float):
         physics_object.body.angle = math.radians(rotation)
 
     def set_velocity(self, sprite: Sprite, velocity: tuple[float, float]):
-        """Apply an impulse force on a sprite"""
+        """Directly set the velocity of a sprite known to the engine.
+
+        .. warning:: Avoid using this on any :py:attr:`DYNAMIC` objects!
+
+        This function is meant for :py:attr:`KINEMATIC` objects. Using
+        it on a sprite added as :py:attr:`DYNAMIC` can cause strange and
+        very broken behavior.
+
+        To learn more, please see:
+
+        * Pymunk's documentation on :py:attr:`~pymunk.Body.DYNAMIC` and
+          :py:attr:`~pymunk.Body.KINEMATIC`
+
+        """
         physics_object = self.get_physics_object(sprite)
         if physics_object.body is None:
             raise PymunkException(
@@ -440,7 +609,25 @@ def set_horizontal_velocity(self, sprite: Sprite, velocity: float):
         physics_object.body.velocity = new_cv
 
     def set_friction(self, sprite: Sprite, friction: float):
-        """Apply force to a Sprite."""
+        """Set the friction a sprite experiences against other surfaces.
+
+        This is how "rough" a sprite is during a collision with others:
+
+        * ``0.0`` is the lowest value allowed (absolute slipperiness)
+        * Higher values slide less on surfaces and other objects
+
+        Pymunk allows setting ``friction`` higher than ``1.0``, but very
+        high values might not have meaningful gameplay impact.
+
+        .. _Simple Wikipedia's Article on Friction: https://simple.wikipedia.org/wiki/Friction
+
+        To learn more, please see:
+
+        * The :ref:`pymunk_platformer_tutorial-add_physics_engine` step
+          of the :ref:`pymunk_platformer_tutorial`
+        * `Simple Wikipedia's Article on Friction`_
+        * :py:attr:`pymunk.Poly.friction`
+        """
         physics_object = self.sprites[sprite]
         if physics_object.shape is None:
             raise PymunkException(
diff --git a/doc/conf.py b/doc/conf.py
@@ -177,7 +177,9 @@
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'python': ('https://docs.python.org/3', None),
                        'pyglet': ('https://pyglet.readthedocs.io/en/latest/', None),
-                       'PIL': ('https://pillow.readthedocs.io/en/stable', None)}
+                       'PIL': ('https://pillow.readthedocs.io/en/stable', None),
+                       'pymunk': ('https://www.pymunk.org/en/latest/', None)
+                       }
 
 # Fix: "more than one target found for cross-reference 'Texture'"
 suppress_warnings = [
diff --git a/doc/tutorials/pymunk_platformer/index.rst b/doc/tutorials/pymunk_platformer/index.rst
@@ -155,6 +155,9 @@ tiled map you created:
 * :ref:`pymunk_demo_platformer_04`
 * :ref:`pymunk_demo_platformer_04_diff`
 
+
+.. _pymunk_platformer_tutorial-add_physics_engine:
+
 Add Physics Engine
 ------------------
 
@@ -503,7 +506,7 @@ In the ``setup`` method, load in the sprite list from the tmx layer.
 
 .. literalinclude:: pymunk_demo_platformer_11.py
     :caption: Moving Platforms - Adding the sprite list
-    :lines: 227
+    :lines: 230-231
 
 Also in the ``setup`` method, we need to add these sprites to the physics engine.
 In this case we'll add the sprites as ``KINEMATIC``. Static sprites don't move.
