Cache distinct separating axes per hit box

[pvcraven]

Stacked on #2894. This targets perf/collision-aabb so the diff only shows this change. Please merge #2894 first; GitHub will then retarget this to development.

Summary

After #2894, the polygon test still projected onto every non axis-aligned edge normal of both hit boxes, about 1 µs per axis. Many of those axes are duplicates:

• Opposite sides of a polygon are parallel, e.g. the default octagon hit box has 4 diagonal edges but only 2 directions.
• Two sprites with the same angle (all unrotated sprites, for example) share directions.

This PR caches each hit box's distinct edge directions and tests each direction only once per pair.

Pair	Axes tested before	Axes tested now
Two unrotated octagons	8	2
Two octagons, both at 30°	16	4

How it works

• Per hit box cache. HitBox._get_axes() returns a dict mapping a rounded unit direction to an edge normal. Merging the two hit boxes' dicts (axes1 | axes2) drops directions they share.
• Kept when moving. Directions don't depend on position. Duplicates are removed once from the raw points, and the handful of remaining directions are scaled and rotated when scale or angle changes (both keep parallel edges parallel). So a moving, non-rotating sprite never recomputes its axes, and a rotating one only transforms 2–4 vectors.
• Subclasses stay correct. If a subclass overrides get_adjusted_points(), the axes come from its adjusted points instead of assuming the built-in transform.
• Exact touches stay exact. Rounded unit vectors are only used as dict keys to spot parallel edges. Projections use the unnormalized normal (e.g. (4.5, -2.25)), which keeps exact arithmetic for common sizes and positions. An earlier version projected onto unit normals, and rounding then turned some exact touches into collisions.

Right angles now give exact coordinates

sin(radians(180)) is about 1.2e-16, not 0, so a hit box rotated 90°/180°/270° had coordinates like 15.999999999999998. Whether two exactly touching sprites collided could depend on that noise, and it differed from the unrotated case. RotatableHitBox now uses exact cosine/sine values for multiples of 90°. This was needed so that nearly axis-aligned normals don't appear at right angles, but it's also a small accuracy improvement on its own (e.g. sprite.left on a tile rotated 90° is now exact).

Benchmarks

µs per call, best of 5, same script against perf/collision-aabb (#2894) and this branch.

Case	#2894	This PR
octagon / octagon, overlapping	11.96	4.55
octagon / octagon, both rotated 30°, overlapping	20.83	6.89
octagon / box, overlapping	6.32	4.15
octagon / octagon, one moving each call	15.53	7.85
meteor vs 200 randomly rotated meteors, brute force	171.7	124.2
coin vs 900 densely packed coins, brute force	405.0	347.0
moving player vs 400 tiles, spatial hash	16.2	13.1
worst case: one octagon rotating every call	20.31	17.95
worst case: both octagons rotating every call	28.19	23.63
box / box, overlapping (no axes before or after)	2.31	2.03

Even when the cache is rebuilt on every call (rotating sprites), it's still faster than before.

get_adjusted_points() recompute cost: angle 0 is ~6% faster (sine/cosine are no longer computed when unused), 90° is unchanged, and other angles are ~0.1 µs (~4%) slower because of the right-angle check.

Correctness

• Stress test: 200,000 random sprite pairs (box, octagon, long thin, player, and a detailed/concave meteor hit box; ±scale on each axis; 60% sharing an angle from 0/90/180/270/-90/45/30/450/random; positions on a half/quarter-pixel grid, so exact touches are common), both argument orders. 0 mismatches against a full SAT on every edge plus the x/y axes.
• The earlier reference had a gap for concave shapes: it used only edge normals, which can miss a separation for concave hit boxes, and those can come from the detailed algorithm. The one pair that disagreed had bounding boxes that don't overlap at all, so this PR's answer was the correct one (Speed up sprite collision with cached bounds and a leaner SAT #2894 gives the same answer). The reference in test_check_for_collision_matches_reference now also checks the x and y axes, and the test now includes the detailed meteor hit box and same-angle pairs.
• New hit box tests:
  • Exact points at 90/180/270/-90/450°.
  • A box has 0 axes and an octagon has 2.
  • The cache is kept when moving and recomputed for scale/angle changes, including 45°, where diagonals become axis-aligned.
  • The subclass fallback.
• Deliberate bugs are caught: making the axes ignore rotation, or rotate the wrong way, makes the tests fail.
• Full unit suite: 1095 passed. The 3 failures (test_draw_primitives, test_render_sprite_solid_pixels, test_get_image) also fail on development on my machine. Ruff is clean, and mypy reports no errors in the changed files.

Known approximation

Two edges count as parallel if their unit directions agree to 9 decimal places, so a pair of edges less than ~1e-9 radians apart shares one test. That could only change the result when the sprites are within about a billionth of their size of touching.

🤖 Generated with Claude Code