Merge #458

458: Saften TargetSprite r=pathunstrom a=serin-delaunay

* Crash on negative exponential_speed to prevent imaginary values.
* Document effects of parameter value ranges.
* Prevent zero division when max speed is negative and sprite is at target.

Tests still only cover the standard usage, not error conditions or negative speeds.

Co-authored-by: Serin Delaunay <serin.delaunay@gmail.com>

ppb/features/default_sprites.py

@@ -7,10 +7,14 @@ class TargetSprite(ppb.Sprite):
 
     :param target: Vector that the sprite moves towards.
     :param speed: Distance per second that the sprite travels with linear motion.
+    Negative values cause movement away from the target.
     :param exponential_speed: Fraction of the distance to the target that the sprite travels
-    per second with exponential motion. Should normally be in the range [0.0, 1.0].
-    :param max_speed: Maximum distance per second that the sprite can travel.
+    per second with exponential motion. Must be less than 1.
+    Negative values cause movement away from the target.
+    :param max_speed: Maximum distance per second that the sprite can travel towards the target.
+    Negative values cause movement away from the target.
     :param min_speed: Minimum distance per second that the sprite travels when not in range of the target.
+    Non-negative values prevent movement away from the target.
     """
     target = ppb.Vector(0, 0)
     speed = 1.0
@@ -20,9 +24,14 @@ class TargetSprite(ppb.Sprite):
 
     def on_update(self, update_event, signal):
         if self.max_speed < self.min_speed:
-            raise ValueError("TargetSprite maximum speed cannot be less than minimum speed.")
+            raise ValueError(f"{type(self).__name__} maximum speed cannot be less than minimum speed.")
+        if self.exponential_speed > 1.0:
+            raise ValueError(f"{type(self).__name__} exponential speed cannot be greater than 1.")
         offset = self.target - self.position
         distance_to_target = offset.length
+        if distance_to_target < 0.0001:
+            self.position = self.target
+            return
         max_distance = self.max_speed * update_event.time_delta
         min_distance = self.min_speed * update_event.time_delta
         linear_distance = self.speed * update_event.time_delta