Add RawHitBox TypedDict and normalize points to tuples

Add a RawHitBox TypedDict for typed serialization in to_dict/from_dict.
Normalize all points to tuples of tuples on construction, add_region,
and in adjusted point calculation for immutability and consistency.
Update tests to expect tuple-based comparisons.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Cleptomania

arcade/hitbox/__init__.py

@@ -2,7 +2,7 @@
 
 from arcade.types import Point2List
 
-from .base import HitBox, HitBoxAlgorithm
+from .base import HitBox, HitBoxAlgorithm, RawHitBox
 from .bounding_box import BoundingHitBoxAlgorithm
 
 from .simple import SimpleHitBoxAlgorithm
@@ -59,6 +59,7 @@ def calculate_hit_box_points_detailed(
 __all__ = [
     "HitBoxAlgorithm",
     "HitBox",
+    "RawHitBox",
     "SimpleHitBoxAlgorithm",
     "PymunkHitBoxAlgorithm",
     "BoundingHitBoxAlgorithm",

arcade/hitbox/base.py

@@ -4,14 +4,21 @@
 import json
 from math import cos, radians, sin
 from pathlib import Path
-from typing import Any
+from typing import Any, TypedDict
 
 from PIL.Image import Image
 from typing_extensions import Self
 
 from arcade.types import EMPTY_POINT_LIST, Point2, Point2List
 
-__all__ = ["HitBoxAlgorithm", "HitBox"]
+__all__ = ["HitBoxAlgorithm", "HitBox", "RawHitBox"]
+
+
+class RawHitBox(TypedDict):
+    """Typed dictionary representing the serialized form of a :py:class:`HitBox`."""
+
+    version: int
+    regions: dict[str, Point2List]
 
 
 class HitBoxAlgorithm:
@@ -134,14 +141,21 @@ class HitBox:
 
         loaded = HitBox.load("hitbox.json")
 
-        # Dict round-trip
+        # Dict round-trip (see RawHitBox for the schema)
         data = box.to_dict()
         copy = HitBox.from_dict(data)
 
+    .. note::
+
+        All points are normalized to tuples of tuples on construction.
+        Any sequence type is accepted as input, but regions will always
+        store tuples internally.
+
     Args:
         points:
             Either a single ``Point2List`` (creates a ``"default"`` region)
             or a ``dict[str, Point2List]`` mapping region names to point lists.
+            Points are normalized to tuples on storage.
         position:
             The center around which the points will be offset.
         scale:
@@ -160,9 +174,11 @@ def __init__(
         angle: float = 0.0,
     ):
         if isinstance(points, dict):
-            self._regions: dict[str, Point2List] = dict(points)
+            self._regions: dict[str, Point2List] = {
+                name: tuple(tuple(p) for p in pts) for name, pts in points.items()
+            }
         else:
-            self._regions = {self.DEFAULT_REGION: points}
+            self._regions = {self.DEFAULT_REGION: tuple(tuple(p) for p in points)}
 
         self._position = position
         self._scale = scale
@@ -205,7 +221,7 @@ def add_region(self, name: str, points: Point2List) -> None:
             name: The name for the new region.
             points: The polygon points for the region.
         """
-        self._regions[name] = points
+        self._regions[name] = tuple(tuple(p) for p in points)
         self._is_single_region = len(self._regions) == 1
         self._adjusted_cache_dirty = True
 
@@ -324,7 +340,7 @@ def _adjust_point(point: Point2) -> Point2:
             return (x + position_x, y + position_y)
 
         self._adjusted_regions = {
-            name: [_adjust_point(p) for p in pts] for name, pts in self._regions.items()
+            name: tuple(_adjust_point(p) for p in pts) for name, pts in self._regions.items()
         }
         self._adjusted_cache_dirty = False
 
@@ -352,39 +368,36 @@ def get_all_adjusted_polygons(self) -> list[Point2List]:
 
     # --- Serialization ---
 
-    def to_dict(self) -> dict:
+    def to_dict(self) -> RawHitBox:
         """
-        Serialize the hitbox shape to a dictionary.
+        Serialize the hitbox shape to a :py:class:`RawHitBox` dictionary.
 
         Only the region definitions (point data) are serialized.
         Position, scale, and angle are runtime state and are not included.
         """
         return {
             "version": 1,
-            "regions": {name: [list(p) for p in pts] for name, pts in self._regions.items()},
+            "regions": {name: pts for name, pts in self._regions.items()},
         }
 
     @classmethod
     def from_dict(
         cls,
-        data: dict,
+        data: RawHitBox,
         position: Point2 = (0.0, 0.0),
         scale: Point2 = (1.0, 1.0),
         angle: float = 0.0,
     ) -> HitBox:
         """
-        Create a HitBox from a serialized dictionary.
+        Create a HitBox from a :py:class:`RawHitBox` dictionary.
 
         Args:
-            data: The dictionary to deserialize from.
+            data: A :py:class:`RawHitBox` dictionary to deserialize from.
             position: The center offset.
             scale: The scaling factors.
             angle: The rotation angle in degrees.
         """
-        regions: dict[str, Point2List] = {
-            name: tuple(tuple(p) for p in pts) for name, pts in data["regions"].items()
-        }
-        return cls(points=regions, position=position, scale=scale, angle=angle)
+        return cls(points=data["regions"], position=position, scale=scale, angle=angle)
 
     def save(self, path: str | Path) -> None:
         """

tests/unit/hitbox/test_hitbox.py

@@ -5,8 +5,8 @@
 import pytest
 from arcade import hitbox
 
-points = [(0.0, 0.0), (0.0, 10.0), (10.0, 10.0), (10.0, 0.0)]
-rot_90 = [(0.0, 0.0), (10.0, 0), (10.0, -10.0), (0.0, -10.0)]
+points = ((0.0, 0.0), (0.0, 10.0), (10.0, 10.0), (10.0, 0.0))
+rot_90 = ((0.0, 0.0), (10.0, 0), (10.0, -10.0), (0.0, -10.0))
 
 
 def test_module():
@@ -34,14 +34,14 @@ def test_scale():
     hb = hitbox.HitBox(points)
     hb.scale = (2.0, 2.0)
     assert hb.scale == (2.0, 2.0)
-    assert hb.get_adjusted_points() == [(0.0, 0.0), (0.0, 20.0), (20.0, 20.0), (20.0, 0.0)]
+    assert hb.get_adjusted_points() == ((0.0, 0.0), (0.0, 20.0), (20.0, 20.0), (20.0, 0.0))
 
 
 def test_position():
     hb = hitbox.HitBox(points)
     hb.position = (10.0, 10.0)
     assert hb.position == (10.0, 10.0)
-    assert hb.get_adjusted_points() == [(10.0, 10.0), (10.0, 20.0), (20.0, 20.0), (20.0, 10.0)]
+    assert hb.get_adjusted_points() == ((10.0, 10.0), (10.0, 20.0), (20.0, 20.0), (20.0, 10.0))
 
 
 def test_rotation():
@@ -74,8 +74,8 @@ def test_multi_region_create():
     assert hb.has_region("body")
     assert hb.has_region("head")
     assert not hb.has_region("default")
-    assert hb.regions["body"] == body_pts
-    assert hb.regions["head"] == head_pts
+    assert hb.regions["body"] == tuple(tuple(p) for p in body_pts)
+    assert hb.regions["head"] == tuple(tuple(p) for p in head_pts)
 
 
 def test_multi_region_adjusted():
@@ -84,8 +84,8 @@ def test_multi_region_adjusted():
     hb = hitbox.HitBox({"body": body_pts, "head": head_pts}, position=(5.0, 5.0))
     body_adj = hb.get_adjusted_points("body")
     head_adj = hb.get_adjusted_points("head")
-    assert body_adj == [(5.0, 5.0), (5.0, 15.0), (15.0, 15.0), (15.0, 5.0)]
-    assert head_adj == [(7.0, 15.0), (7.0, 20.0), (13.0, 20.0), (13.0, 15.0)]
+    assert body_adj == ((5.0, 5.0), (5.0, 15.0), (15.0, 15.0), (15.0, 5.0))
+    assert head_adj == ((7.0, 15.0), (7.0, 20.0), (13.0, 20.0), (13.0, 15.0))
 
 
 def test_multi_region_boundaries():
@@ -134,7 +134,7 @@ def test_single_region_fast_path():
     hb = hitbox.HitBox(points)
     polys = hb.get_all_adjusted_polygons()
     assert len(polys) == 1
-    assert polys[0] == list(points)
+    assert polys[0] == points
 
 
 # --- Serialization tests ---
@@ -167,7 +167,7 @@ def test_from_dict():
     }
     hb = hitbox.HitBox.from_dict(d)
     assert hb.points == ((0.0, 0.0), (0.0, 10.0), (10.0, 10.0), (10.0, 0.0))
-    assert hb.get_adjusted_points() == [(0.0, 0.0), (0.0, 10.0), (10.0, 10.0), (10.0, 0.0)]
+    assert hb.get_adjusted_points() == ((0.0, 0.0), (0.0, 10.0), (10.0, 10.0), (10.0, 0.0))
 
 
 def test_roundtrip_dict():

tests/unit/sprite/test_sprite_hitbox.py

@@ -15,27 +15,27 @@ def test_1():
     print()
     hitbox = my_sprite.hit_box.get_adjusted_points()
     print(f"Hitbox: {my_sprite.scale} -> {my_sprite.hit_box.points} -> {hitbox}")
-    assert hitbox == [(90.0, 90.0), (90.0, 110.0), (110.0, 110.0), (110.0, 90.0)]
+    assert hitbox == ((90.0, 90.0), (90.0, 110.0), (110.0, 110.0), (110.0, 90.0))
 
     my_sprite.scale = 0.5, 0.5
     hitbox = my_sprite.hit_box.get_adjusted_points()
     print(f"Hitbox: {my_sprite.scale} -> {my_sprite.hit_box.points} -> {hitbox}")
-    assert hitbox == [(95.0, 95.0), (95.0, 105.0), (105.0, 105.0), (105.0, 95.0)]
+    assert hitbox == ((95.0, 95.0), (95.0, 105.0), (105.0, 105.0), (105.0, 95.0))
 
     my_sprite.scale = 1.0
     hitbox = my_sprite.hit_box.get_adjusted_points()
     print(f"Hitbox: {my_sprite.scale} -> {my_sprite.hit_box.points} -> {hitbox}")
-    assert hitbox == [(90.0, 90.0), (90.0, 110.0), (110.0, 110.0), (110.0, 90.0)]
+    assert hitbox == ((90.0, 90.0), (90.0, 110.0), (110.0, 110.0), (110.0, 90.0))
 
     my_sprite.scale = 2.0
     hitbox = my_sprite.hit_box.get_adjusted_points()
     print(f"Hitbox: {my_sprite.scale} -> {my_sprite.hit_box.points} -> {hitbox}")
-    assert hitbox == [(80.0, 80.0), (80.0, 120.0), (120.0, 120.0), (120.0, 80.0)]
+    assert hitbox == ((80.0, 80.0), (80.0, 120.0), (120.0, 120.0), (120.0, 80.0))
 
     my_sprite.scale = 2.0
     hitbox = my_sprite.hit_box.get_adjusted_points()
     print(f"Hitbox: {my_sprite.scale} -> {my_sprite.hit_box.points} -> {hitbox}")
-    assert hitbox == [(80.0, 80.0), (80.0, 120.0), (120.0, 120.0), (120.0, 80.0)]
+    assert hitbox == ((80.0, 80.0), (80.0, 120.0), (120.0, 120.0), (120.0, 80.0))
 
 
 def test_2():