Name scale properties on Sprites to things that make sense (#2021)

* incomplete scale fix

* fix a bunch of tests

* fix more tests

* typo

* fix the one broken test and speed up .scale setter

* fix docstrings

* Fix examples

* typing go brrr

* Remove overly strict Point annotation

* Fix misuse of Point annotation which should be Point2

* Annotate HitBox scale __init__ arguments as Point2

* Annotate BasicSprite scale return as Point2

* Fix set_size tests w/ notes on problems with == in pyglet==2.1dev2

* Add temp fix for pyglet 2.1dev2

* Remove Vec2 from test_set_size()

* Update BasicSprite.scale and tests for it

* Make .scale convert to Vec2 on return

* Update scale unit tests to use tuples

* Fix formatting to make CI happy

* Add optimized validation for BasicSprite.size + tests

* Optimize & clean up BasicSprite.scale_x setter

* Remove if check around texture since we are guaranteed to have one now

* Rename scale_x argument from new_value to new_scale_x

* Unpack self._scale into old_scale_*

* Remove redundant scale setting for y

* Apply new scale to the hitbox first to raise exceptions earlier

* Optimize & clean up BasicSprite.scale_y setter

* Remove if check around texture since we are guaranteed to have one now

* Rename scale_x argument from new_value to new_scale_x

* Unpack self._scale into old_scale_*

* Remove redundant scale setting for x

* Apply new scale to the hitbox first to raise exceptions earlier

* Optimize and clean up scale setter

* Rename new_value to new_scale

* Assign to scale_x and scale_y instead of immediate tuple creation

* Add comments about hot code path asking not to DRY it

* Add exception checks for unpack

* Reorder and reduce use of dot and index acccess

* Remove extra line

* Revert use of assert in size.setter since digi was right

* Clean up rescale_relative_to_point's insides

* Significantly redeuce dot and index access in rescale_relative_to_point

* Precache re-used quantities

* Comments for clarity

* Update rescale_relative_to_point's docstring

* Use scale instead of removed scale_xy

* Convert to more pyglet/Google-style

* Unify rescale*_relative_to_point methods

* Add vector unpack check logic to rescale_relative_to_point

* Update signature annotations

* Update docstring

* Rename factor argument to scale_by

* Delete body of rescale_xy_relative_to_point

* Update docstring to point to rescale_relative_to_point with deprecation

* Add @warning wrapper to rescale_xy_relative_to_point

* Apply auto-formatting

* Fix typo

* Make Sphinx build

* Fix use of Point with Point2

* Add detailed explanation of seemingly strange Vec2 usage

---------

Co-authored-by: Darren Eberly <darren@eber.ly>
Co-authored-by: Einar Forselv <eforselv@gmail.com>
Co-authored-by: pushfoo <36696816+pushfoo@users.noreply.github.com>

arcade/__init__.py

@@ -58,6 +58,17 @@ def configure_logging(level: Optional[int] = None):
 # noinspection PyPep8
 import pyglet
 
+# TODO: Remove ASAP after pyglet >= 2.1dev2 is out
+if pyglet.version == "2.1.dev2":
+    # Temporary monkeypatch via deletion since dev2 still includes
+    # overly-specific __eq__ behavior. Later pyglet commits restore
+    # equality with same-valued tuples by deleting the __eq__ methods.
+    from pyglet import math as _pyglet_math
+
+    del _pyglet_math.Vec2.__eq__
+    del _pyglet_math.Vec3.__eq__
+    del _pyglet_math.Vec4.__eq__
+
 # Env variable shortcut for headless mode
 if os.environ.get("ARCADE_HEADLESS"):
     pyglet.options["headless"] = True

arcade/examples/particle_fireworks.py

@@ -360,7 +360,7 @@ def firework_spark_mutator(particle: FadeParticle):
 
 
 def rocket_smoke_mutator(particle: LifetimeParticle):
-    particle.scale = lerp(0.5, 3.0, particle.lifetime_elapsed / particle.lifetime_original)
+    particle.scale = lerp(0.5, 3.0, particle.lifetime_elapsed / particle.lifetime_original)  # type: ignore
 
 
 def main():

arcade/examples/sprite_health.py

@@ -52,7 +52,7 @@ def __init__(self, bar_list: arcade.SpriteList) -> None:
             scale=SPRITE_SCALING_PLAYER,
         )
         self.indicator_bar: IndicatorBar = IndicatorBar(
-            self, bar_list, (self.center_x, self.center_y), scale=1.5,
+            self, bar_list, (self.center_x, self.center_y), scale=(1.5, 1.5),
         )
         self.health: int = PLAYER_HEALTH
 
@@ -98,7 +98,7 @@ def __init__(
         width: int = 100,
         height: int = 4,
         border_size: int = 4,
-        scale: float = 1.0,
+        scale: Tuple[float, float] = (1.0, 1.0),
     ) -> None:
         # Store the reference to the owner and the sprite list
         self.owner: Player = owner
@@ -110,7 +110,7 @@ def __init__(
         self._center_x: float = 0.0
         self._center_y: float = 0.0
         self._fullness: float = 0.0
-        self._scale: float = 1.0
+        self._scale: Tuple[float, float] = (1.0, 1.0)
 
         # Create the boxes needed to represent the indicator bar
         self._background_box: arcade.SpriteSolidColor = arcade.SpriteSolidColor(
@@ -206,8 +206,8 @@ def fullness(self, new_fullness: float) -> None:
         else:
             # Set the full_box to be visible incase it wasn't then update the bar
             self.full_box.visible = True
-            self.full_box.width = self._bar_width * new_fullness * self.scale
-            self.full_box.left = self._center_x - (self._bar_width / 2) * self.scale
+            self.full_box.width = self._bar_width * new_fullness * self.scale[0]
+            self.full_box.left = self._center_x - (self._bar_width / 2) * self.scale[0]
 
     @property
     def position(self) -> Tuple[float, float]:
@@ -224,15 +224,15 @@ def position(self, new_position: Tuple[float, float]) -> None:
             self.full_box.position = new_position
 
             # Make sure full_box is to the left of the bar instead of the middle
-            self.full_box.left = self._center_x - (self._bar_width / 2) * self.scale
+            self.full_box.left = self._center_x - (self._bar_width / 2) * self.scale[0]
 
     @property
-    def scale(self) -> float:
+    def scale(self) -> Tuple[float, float]:
         """Returns the scale of the bar."""
         return self._scale
 
     @scale.setter
-    def scale(self, value: float) -> None:
+    def scale(self, value: Tuple[float, float]) -> None:
         """Sets the new scale of the bar."""
         # Check if the scale has changed. If so, change the bar's scale
         if value != self.scale:

arcade/hitbox/base.py

@@ -103,7 +103,7 @@ def __init__(
         self,
         points: Point2List,
         position: Point2 = (0.0, 0.0),
-        scale: tuple[float, float] = (1.0, 1.0),
+        scale: Point2 = (1.0, 1.0),
     ):
         self._points = points
         self._position = position
@@ -249,7 +249,7 @@ def __init__(
         *,
         position: tuple[float, float] = (0.0, 0.0),
         angle: float = 0.0,
-        scale: tuple[float, float] = (1.0, 1.0),
+        scale: Point2 = (1.0, 1.0),
     ):
         super().__init__(points, position=position, scale=scale)
         self._angle: float = angle

arcade/pymunk_physics_engine.py

@@ -189,7 +189,7 @@ def velocity_callback(
 
         # Set the physics shape to the sprite's hitbox
         poly = sprite.hit_box.points
-        scaled_poly = [[x * sprite.scale for x in z] for z in poly]
+        scaled_poly = [[x * sprite.scale_x for x in z] for z in poly]
         shape = pymunk.Poly(body, scaled_poly, radius=radius)  # type: ignore
 
         # Set collision type, used in collision callbacks

arcade/sprite/animated.py

@@ -335,5 +335,5 @@ def update_animation(self, delta_time: float = 1 / 60) -> None:
         if self._texture is None:
             print("Error, no texture set")
         else:
-            self.width = self._texture.width * self.scale
-            self.height = self._texture.height * self.scale
+            self.width = self._texture.width * self.scale_x
+            self.height = self._texture.height * self.scale_x