Improve Robustness and Clarity of FastQuadTree Implementation

[JaskRendix]

PR improves the FastQuadTree class for quadtree collision detection in the following ways:

• adds a check to ensure the items list is not empty, avoiding cryptic errors and improving API safety
• introduces a get_rect helper function to cleanly support objects with a .rect attribute, ensuring consistency throughout
• stores the quad’s boundary as an instance attribute for better clarity and use in collision filtering
• filters out irrelevant hits early by verifying boundary.colliderect(rect) before checking children quadrants
• fixes potential TypeError in __iter__ by chaining only non-None quadrant lists
• cleaner code: uses explicit if statements for quadrant placement rather than short-circuiting and, reorders logic for readability and consistency and applies correct type annotations using Optional and explicit list[Rect]
• added quadtree_vs_brute_benchmark.py, a performance comparison script between brute-force collision detection and FastQuadTree, including detailed timing metrics for build and query operations
• added quadtree_depth_benchmark.py, a benchmarking tool using CLI arguments to assess the impact of quadtree depth on build and query performance, outputs timing results across multiple depth levels to assist with fine-tuning configurations
• added quadtree_visualizer.py, a standalone tool for visually inspecting FastQuadTree query behavior, it renders tile rectangles, highlights collision hits from spatial queries, and includes an interactive toggle for displaying results

Benchmark Configuration:
  Items     : 5000
  Queries   : 1000
  Min Depth : 2
  Max Depth : 6
FastQuadTree Benchmark Results
Depth |  Build (s) |  Query (s)
--------------------------------
    2 | 0.003998 | 0.114722
    3 | 0.005537 | 0.106174
    4 | 0.008422 | 0.129101
    5 | 0.013289 | 0.244471
    6 | 0.023701 | 0.328741

this shows increasing build time with depth, and a sweet spot around depth 3 where query time is lowest.

Benchmark: 5000 rects, 1000 queries, depth=4
FastQuadTree:
  Build Time:  0.013068s
  Query Time:  0.163915s
Brute-force:
  Setup Time:  negligible
  Query Time:  0.282060s

FastQuadTree is ~35% faster for querying under these conditions.

[bitcraft]

could you elaborate on what the changes are for damage detection?

[JaskRendix]

@bitcraft sure, the _process_sprite_damage method explicitly handles the damage detection and determines whether tiles need to be added to the blit_list based on overlapping layers, this avoids cluttering the primary drawing logic

[bitcraft]

have you verified there are no regressions to the visuals?

[JaskRendix]

I bailed on the visuals side for now, figured I’d zero in on just cleaning up the FastQuadTree class