WIP #193 - No overshoot on move_towards_point

Added an optional parameter to `move_towards_point()` named
`overshoot` that is `False` by default. Actors will now
automatically come to stop at the target when moving towards
a point (preventing the rapid back and forth from before)
unless `overshoot` is supplied as `True`.

Updated documentation to reflect this change.

Author: Mambouna

doc/builtins.rst

@@ -638,10 +638,15 @@ actors around their rotation easier, Pygame Zero provides built-in functions.
     Moves the actor the given distance along the given angle.
 
 
-.. method:: Actor.move_towards_point(point, distance)
+.. method:: Actor.move_towards_point(point, distance, [overshoot])
 
     Moves the actor the given distance towards the given point of X and Y.
 
+    By default, if the distance to the point is smaller than the given
+    distance, the actor will only move up to the point but not overshoot it.
+    If the optional parameter ``overshoot`` is given as True however, the
+    actor will move past the target point if the given distance is far enough.
+
 
 .. method:: Actor.move_forward(distance)
 
@@ -685,13 +690,13 @@ the game window::
     def update():
         # To just read the value of the global variable,
         # we don't have to do anything else.
-        ship.move_towards_point(mouse_position)
+        ship.move_towards_point(mouse_position, 5)
 
-*Note:* When using ``move_towards_point()``, if the distance overshoots the target
-and the function is called again every frame (for example in ``update()``), the
-actor will rapidly jump back and forth since the angle to the target point gets
-inverted every frame. To prevent this, check the distance to the target point
-and adjust the length of the movement if necessary.
+*Note:* When using ``move_towards_point()`` with ``overshoot=True``, if the
+function is called every frame (for example in ``update()``), the actor will
+rapidly jump back and forth since the angle to the target point gets inverted
+every frame. To prevent this, use ``move_towards_point()`` without ``overshoot``
+or make sure it is not called rapidly with ``overshoot``.
 
 
 .. _transparency:

src/pgzero/actor.py

@@ -366,11 +366,15 @@ def move_towards_angle(self, angle, distance):
         self.x += move_x
         self.y += move_y
 
-    def move_towards_point(self, point, distance):
+    def move_towards_point(self, point, distance, overshoot=False):
         """Figure out the angle to the given point and then
         move the actor towards it by the given distance."""
         angle = self.angle_to(point)
-        self.move_towards_angle(angle, distance)
+        if overshoot:
+            self.move_towards_angle(angle, distance)
+        else:
+            m_distance = min(self.distance_to(point), distance)
+            self.move_towards_angle(angle, m_distance)
 
     def move_forward(self, distance):
         """Move the actor in the direction it is facing."""