Fix collision method and duplicate oddities, document touching

[pvcraven]

Summary

Three small collision inconsistencies. The first two are behavior changes; the third is documentation only.

1. CollisionMethod.SPATIAL without a spatial hash

Before: SPATIAL on a list without a spatial hash always used the GPU, even for a one-sprite list. Someone choosing SPATIAL is likely calling this many times per frame, which is when the GPU path is slowest. It also needs an open window: without one it raised NoArcadeWindowError, where AUTO on the same list worked.

Now: it chooses the same way as AUTO. Lists of 1500 or fewer check every sprite, and larger lists use the GPU. With a spatial hash, nothing changes, and no other method changes.

2. Duplicates from check_for_collision_with_lists

Before: a sprite in more than one of the lists was returned once per list.

Now: each colliding sprite is returned once, in the order first found. This only runs when more than one list is passed and there are 2 or more hits.

The built-in physics engines only check whether the result is empty, or loop over it, so they don't rely on duplicates.

3. Touching edges (docs only)

Hit boxes that only touch, sharing an edge or a corner, don't collide. A point exactly on an edge, though, counts for get_sprites_at_point and collides_with_point. This has to stay as it is: the physics engines push a sprite until it no longer collides, so a sprite resting on the ground must not count as colliding with it.

So this PR documents the difference on check_for_collision, collides_with_sprite, get_sprites_at_point, collides_with_point, and get_sprites_in_rect. It also corrects get_sprites_in_rect's docs, which said sprites touching the rectangle were returned (they aren't) and described the rectangle as a tuple (it's a Rect).

Tests

• The test_collision_method_paths table now has SPATIAL without a hash checking every sprite on small lists, using the GPU on large ones, and checking every sprite on WebGL. Each case runs with the enum and with the plain number, through both functions.
• test_check_for_collision_with_lists_no_duplicates covers first-found order, the same list passed twice, a generator of lists, and a spatial-hashed list (compared as a set, since a spatial hash returns sprites in no particular order).
• test_touching_edges pins down the documented behavior: edge and corner touches don't collide (sprite to sprite, list, and rect), while points on an edge or corner count.
• On development, only the changed SPATIAL rows and the duplicates test fail. test_touching_edges passes there too, since that behavior is unchanged.
• Full unit suite: 1134 passed, including the physics engine tests. The 3 failures are the render tests that only fail on my machine. Ruff is clean.

Performance

check_for_collision_with_lists(player, [walls, platforms]), with the old and new versions interleaved in one process (best of 300 rounds):

Case	Before	After
no hits	3.491 µs	3.543 µs
standing on 2 tiles (2 hits, so duplicates are removed)	8.699 µs	8.962 µs

That's about 0.05 µs without hits and 0.26 µs (3%) when duplicates are removed.

🤖 Generated with Claude Code