[pvcraven]

Summary

Fixes #2663: arcade.load_tilemap() and TileMap now give every layer's sprite list a spatial hash by default.

Why

Forgetting the hash on a wall layer is easy to do and expensive. An unneeded hash usually costs little, as Cleptomania pointed out in the issue. Measured on one desktop:

	No hash	With hash
100 bullets checked against 500 wall tiles, per frame	7.8 ms	0.5 ms
100 bullets checked against 2,000 wall tiles, per frame	48 ms	0.6 ms
Moving 20 platforms, per frame	0.012 ms	0.064 ms
Building a 2,000-sprite layer, once	20 ms	51 ms

Changes

• The default: use_spatial_hash defaults to True in load_tilemap() and TileMap().

  • For a layer whose sprites move a lot, such as moving platforms, turn it off with layer_options={"Moving Platforms": {"use_spatial_hash": False}}, or for the whole map with use_spatial_hash=False.
  • The docstrings say this. The platformer tutorial's moving platforms step already turns it off for that layer.

• Unknown layer_options keys now warn. They used to be silently ignored. The warning names the layer and lists the valid options, and points at the code calling load_tilemap():

  UserWarning: Unknown layer_options for layer 'Platforms': use_spatial_hashing. The options are: scaling, use_spatial_hash, hit_box_algorithm, offset, custom_class, custom_class_args, texture_atlas.
  

  It doesn't warn about layer names the map doesn't have, because one layer_options dict is often reused across several level maps.

• Docs:

  • The performance tips page told readers to set "use_spatial_hashing", but the option is "use_spatial_hash", so anyone who followed the sentence got no hash and no error. The section now describes the new default and how to turn it off.
  • Platformer tutorial step 12's note says layers are hashed by default. Its code, which sets "use_spatial_hash": True, is unchanged so the page's line numbers still match.

Breaking: games that relied on the old default get hashed layers. That's usually faster, but slower for layers with many moving sprites. The changelog entry is under Unreleased → Breaking Changes.

Tests

New tests/unit/tilemap/test_spatial_hash_default.py:

• Layers are hashed by default.
• It can be turned off for one layer or for the whole map.
• An unknown option warns and has no effect, and known options don't warn.

3 of the 5 fail on development.

Checks

• Examples: all 15 that load tilemaps run, and none trigger the new warning.
• Full suite: 1816 passed.
• Code checks: ruff, mypy and pyright pass.

🤖 Generated with Claude Code