Document choosing a spatial hash cell size

[pvcraven]

Summary

Documents how to choose spatial_hash_cell_size. The performance tips said the cell size affects collision checks, but not how to choose it, and the SpriteList docs only gave the default. While measuring the Pixel Demolition demo (#2931), I found that the default of 128 is about 16× too slow for tiny sprites.

Changes

• Performance tips: a new "Choosing a Cell Size" section under Spatial Hashing. The advice is to use a cell size about the size of the sprites in the list, because:

  • much bigger cells make each check look at every sprite in the nearby cells;
  • much smaller cells put each sprite in many cells, so adding and moving sprites gets slower.

  It includes a table of measurements and a code example, and links to the Pixel Demolition example.

• SpriteList(spatial_hash_cell_size=...) and enable_spatial_hashing() docstrings: the same advice in one line, plus a link to the section.

Measurements

Measured on my desktop, with a grid of 2,400 sprites:

Sprites in the list	Cell 8	Cell 16	Cell 64	Cell 128 (default)
4 px: 200 collision checks	2.1 ms	2.8 ms	12.2 ms	33.4 ms
64 px: 200 collision checks	5.7 ms	2.6 ms	2.3 ms	3.1 ms
64 px: adding 2,400 sprites	50.7 ms	22.9 ms	13.6 ms	11.6 ms

No code changes. The docs build with sphinx-build -W, the new section renders with its table, and both docstrings link to it. Ruff is clean.

The changelog has an entry under Unreleased → Misc Changes.

🤖 Generated with Claude Code