zombie-escape 1.8.0__py3-none-any.whl → 1.10.1__py3-none-any.whl

zombie_escape/entities.py

@@ -3,7 +3,12 @@
 from __future__ import annotations
 
 import math
-from typing import Callable, Iterable, Self, Sequence
+from typing import Callable, Iterable, Sequence, cast
+
+try:
+    from typing import Self
+except ImportError:  # pragma: no cover - Python 3.10 fallback
+    from typing_extensions import Self
 
 import pygame
 from pygame import rect
@@ -36,7 +41,10 @@ from .entities_constants import (
     ZOMBIE_SEPARATION_DISTANCE,
     ZOMBIE_SIGHT_RANGE,
     ZOMBIE_SPEED,
+    ZOMBIE_TRACKER_SCAN_INTERVAL_MS,
+    ZOMBIE_TRACKER_SCAN_RADIUS_MULTIPLIER,
     ZOMBIE_TRACKER_SCENT_RADIUS,
+    ZOMBIE_TRACKER_SCENT_TOP_K,
     ZOMBIE_TRACKER_SIGHT_RANGE,
     ZOMBIE_TRACKER_WANDER_INTERVAL_MS,
     ZOMBIE_WALL_DAMAGE,
@@ -47,6 +55,8 @@ from .entities_constants import (
     ZOMBIE_WALL_FOLLOW_TARGET_GAP,
     ZOMBIE_WANDER_INTERVAL_MS,
 )
+from .gameplay.constants import FOOTPRINT_STEP_DISTANCE
+from .models import Footprint
 from .render_assets import (
     EnvironmentPalette,
     build_beveled_polygon,
@@ -66,15 +76,162 @@ from .render_assets import (
 )
 from .rng import get_rng
 from .screen_constants import SCREEN_HEIGHT, SCREEN_WIDTH
+from .world_grid import WallIndex, apply_tile_edge_nudge, walls_for_radius
 
 RNG = get_rng()
 
+
+class Wall(pygame.sprite.Sprite):
+    def __init__(
+        self: Self,
+        x: int,
+        y: int,
+        width: int,
+        height: int,
+        *,
+        health: int = INTERNAL_WALL_HEALTH,
+        palette: EnvironmentPalette | None = None,
+        palette_category: str = "inner_wall",
+        bevel_depth: int = INTERNAL_WALL_BEVEL_DEPTH,
+        bevel_mask: tuple[bool, bool, bool, bool] | None = None,
+        draw_bottom_side: bool = False,
+        bottom_side_ratio: float = 0.1,
+        side_shade_ratio: float = 0.9,
+        on_destroy: Callable[[Self], None] | None = None,
+    ) -> None:
+        super().__init__()
+        safe_width = max(1, width)
+        safe_height = max(1, height)
+        self.image = pygame.Surface((safe_width, safe_height), pygame.SRCALPHA)
+        self.palette = palette
+        self.palette_category = palette_category
+        self.health = health
+        self.max_health = max(1, health)
+        self.on_destroy = on_destroy
+        self.bevel_depth = max(0, bevel_depth)
+        self.bevel_mask = bevel_mask or (False, False, False, False)
+        self.draw_bottom_side = draw_bottom_side
+        self.bottom_side_ratio = max(0.0, bottom_side_ratio)
+        self.side_shade_ratio = max(0.0, min(1.0, side_shade_ratio))
+        self._local_polygon = _build_beveled_polygon(
+            safe_width, safe_height, self.bevel_depth, self.bevel_mask
+        )
+        self._update_color()
+        self.rect = self.image.get_rect(topleft=(x, y))
+        # Keep collision rectangular even when beveled visually.
+        self._collision_polygon = None
+
+    def _take_damage(self: Self, *, amount: int = 1) -> None:
+        if self.health > 0:
+            self.health -= amount
+            self._update_color()
+            if self.health <= 0:
+                if self.on_destroy:
+                    try:
+                        self.on_destroy(self)
+                    except Exception as exc:
+                        print(f"Wall destroy callback failed: {exc}")
+                self.kill()
+
+    def _update_color(self: Self) -> None:
+        if self.health <= 0:
+            health_ratio = 0.0
+        else:
+            health_ratio = max(0.0, self.health / self.max_health)
+        fill_color, border_color = resolve_wall_colors(
+            health_ratio=health_ratio,
+            palette_category=self.palette_category,
+            palette=self.palette,
+        )
+        paint_wall_surface(
+            self.image,
+            fill_color=fill_color,
+            border_color=border_color,
+            bevel_depth=self.bevel_depth,
+            bevel_mask=self.bevel_mask,
+            draw_bottom_side=self.draw_bottom_side,
+            bottom_side_ratio=self.bottom_side_ratio,
+            side_shade_ratio=self.side_shade_ratio,
+        )
+
+    def collides_rect(self: Self, rect_obj: rect.Rect) -> bool:
+        if self._collision_polygon is None:
+            return self.rect.colliderect(rect_obj)
+        return _rect_polygon_collision(rect_obj, self._collision_polygon)
+
+    def _collides_circle(
+        self: Self, center: tuple[float, float], radius: float
+    ) -> bool:
+        if not _circle_rect_collision(center, radius, self.rect):
+            return False
+        if self._collision_polygon is None:
+            return True
+        return _circle_polygon_collision(center, radius, self._collision_polygon)
+
+    def set_palette(
+        self: Self, palette: EnvironmentPalette | None, *, force: bool = False
+    ) -> None:
+        """Update the wall's palette to match the current ambient palette."""
+
+        if not force and self.palette is palette:
+            return
+        self.palette = palette
+        self._update_color()
+
+
+class SteelBeam(pygame.sprite.Sprite):
+    """Single-cell obstacle that behaves like a tougher internal wall."""
+
+    def __init__(
+        self: Self,
+        x: int,
+        y: int,
+        size: int,
+        *,
+        health: int = STEEL_BEAM_HEALTH,
+        palette: EnvironmentPalette | None = None,
+    ) -> None:
+        super().__init__()
+        # Slightly inset from the cell size so it reads as a separate object.
+        margin = max(3, size // 14)
+        inset_size = max(4, size - margin * 2)
+        self.image = pygame.Surface((inset_size, inset_size), pygame.SRCALPHA)
+        self._added_to_groups = False
+        self.health = health
+        self.max_health = max(1, health)
+        self.palette = palette
+        self._update_color()
+        self.rect = self.image.get_rect(center=(x + size // 2, y + size // 2))
+
+    def _take_damage(self: Self, *, amount: int = 1) -> None:
+        if self.health > 0:
+            self.health -= amount
+            self._update_color()
+            if self.health <= 0:
+                self.kill()
+
+    def _update_color(self: Self) -> None:
+        """Render a simple square with crossed diagonals that darkens as damaged."""
+        if self.health <= 0:
+            return
+        health_ratio = max(0, self.health / self.max_health)
+        base_color, line_color = resolve_steel_beam_colors(
+            health_ratio=health_ratio, palette=self.palette
+        )
+        paint_steel_beam_surface(
+            self.image,
+            base_color=base_color,
+            line_color=line_color,
+            health_ratio=health_ratio,
+        )
+
+
 MovementStrategy = Callable[
     [
         "Zombie",
         tuple[int, int],
-        list["Wall"],
-        list[dict[str, object]],
+        list[Wall],
+        list[Footprint],
         int,
         int,
         int,
@@ -82,135 +239,17 @@ MovementStrategy = Callable[
     ],
     tuple[float, float],
 ]
-WallIndex = dict[tuple[int, int], list["Wall"]]
-
-
-def build_wall_index(walls: Iterable["Wall"], *, cell_size: int) -> WallIndex:
-    index: WallIndex = {}
-    for wall in walls:
-        if not wall.alive():
-            continue
-        cell_x = int(wall.rect.centerx // cell_size)
-        cell_y = int(wall.rect.centery // cell_size)
-        index.setdefault((cell_x, cell_y), []).append(wall)
-    return index
-
-
 def _sprite_center_and_radius(
     sprite: pygame.sprite.Sprite,
 ) -> tuple[tuple[int, int], float]:
     center = sprite.rect.center
-    radius = float(
-        getattr(sprite, "radius", max(sprite.rect.width, sprite.rect.height) / 2)
-    )
+    if hasattr(sprite, "radius"):
+        radius = float(sprite.radius)
+    else:
+        radius = float(max(sprite.rect.width, sprite.rect.height) / 2)
     return center, radius
 
 
-def walls_for_radius(
-    wall_index: WallIndex,
-    center: tuple[float, float],
-    radius: float,
-    *,
-    cell_size: int,
-    grid_cols: int | None = None,
-    grid_rows: int | None = None,
-) -> list["Wall"]:
-    if grid_cols is None or grid_rows is None:
-        grid_cols, grid_rows = _infer_grid_size_from_index(wall_index)
-    if grid_cols is None or grid_rows is None:
-        return []
-    search_radius = radius + cell_size
-    min_x = max(0, int((center[0] - search_radius) // cell_size))
-    max_x = min(grid_cols - 1, int((center[0] + search_radius) // cell_size))
-    min_y = max(0, int((center[1] - search_radius) // cell_size))
-    max_y = min(grid_rows - 1, int((center[1] + search_radius) // cell_size))
-    candidates: list[Wall] = []
-    for cy in range(min_y, max_y + 1):
-        for cx in range(min_x, max_x + 1):
-            candidates.extend(wall_index.get((cx, cy), []))
-    return candidates
-
-
-def apply_tile_edge_nudge(
-    x: float,
-    y: float,
-    dx: float,
-    dy: float,
-    *,
-    cell_size: int,
-    wall_cells: set[tuple[int, int]] | None,
-    bevel_corners: dict[tuple[int, int], tuple[bool, bool, bool, bool]] | None = None,
-    grid_cols: int,
-    grid_rows: int,
-    strength: float = 0.03,
-    edge_margin_ratio: float = 0.15,
-    min_margin: float = 2.0,
-) -> tuple[float, float]:
-    if dx == 0 and dy == 0:
-        return dx, dy
-    if cell_size <= 0 or not wall_cells:
-        return dx, dy
-    cell_x = int(x // cell_size)
-    cell_y = int(y // cell_size)
-    if cell_x < 0 or cell_y < 0 or cell_x >= grid_cols or cell_y >= grid_rows:
-        return dx, dy
-    speed = math.hypot(dx, dy)
-    if speed <= 0:
-        return dx, dy
-
-    edge_margin = max(min_margin, cell_size * edge_margin_ratio)
-    left_dist = x - (cell_x * cell_size)
-    right_dist = ((cell_x + 1) * cell_size) - x
-    top_dist = y - (cell_y * cell_size)
-    bottom_dist = ((cell_y + 1) * cell_size) - y
-
-    def apply_push(dist: float, direction: float) -> float:
-        if dist >= edge_margin:
-            return 0.0
-        ratio = (edge_margin - dist) / edge_margin
-        return ratio * speed * strength * direction
-
-    if (cell_x - 1, cell_y) in wall_cells:
-        dx += apply_push(left_dist, 1.0)
-    if (cell_x + 1, cell_y) in wall_cells:
-        dx += apply_push(right_dist, -1.0)
-    if (cell_x, cell_y - 1) in wall_cells:
-        dy += apply_push(top_dist, 1.0)
-    if (cell_x, cell_y + 1) in wall_cells:
-        dy += apply_push(bottom_dist, -1.0)
-
-    def apply_corner_push(dist_a: float, dist_b: float, boost: float = 1.0) -> float:
-        if dist_a >= edge_margin or dist_b >= edge_margin:
-            return 0.0
-        ratio = (edge_margin - min(dist_a, dist_b)) / edge_margin
-        return ratio * speed * strength * boost
-
-    if bevel_corners:
-        boosted = 1.25
-        corner_wall = bevel_corners.get((cell_x - 1, cell_y - 1))
-        if corner_wall and corner_wall[2]:
-            push = apply_corner_push(left_dist, top_dist, boosted)
-            dx += push
-            dy += push
-        corner_wall = bevel_corners.get((cell_x + 1, cell_y - 1))
-        if corner_wall and corner_wall[3]:
-            push = apply_corner_push(right_dist, top_dist, boosted)
-            dx -= push
-            dy += push
-        corner_wall = bevel_corners.get((cell_x + 1, cell_y + 1))
-        if corner_wall and corner_wall[0]:
-            push = apply_corner_push(right_dist, bottom_dist, boosted)
-            dx -= push
-            dy -= push
-        corner_wall = bevel_corners.get((cell_x - 1, cell_y + 1))
-        if corner_wall and corner_wall[1]:
-            push = apply_corner_push(left_dist, bottom_dist, boosted)
-            dx += push
-            dy -= push
-
-    return dx, dy
-
-
 def _walls_for_sprite(
     sprite: pygame.sprite.Sprite,
     wall_index: WallIndex,
@@ -218,7 +257,7 @@ def _walls_for_sprite(
     cell_size: int,
     grid_cols: int | None = None,
     grid_rows: int | None = None,
-) -> list["Wall"]:
+) -> list[Wall]:
     center, radius = _sprite_center_and_radius(sprite)
     return walls_for_radius(
         wall_index,
@@ -230,14 +269,6 @@ def _walls_for_sprite(
     )
 
 
-def _infer_grid_size_from_index(wall_index: WallIndex) -> tuple[int | None, int | None]:
-    if not wall_index:
-        return None, None
-    max_col = max(cell[0] for cell in wall_index)
-    max_row = max(cell[1] for cell in wall_index)
-    return max_col + 1, max_row + 1
-
-
 def _circle_rect_collision(
     center: tuple[float, float], radius: float, rect_obj: rect.Rect
 ) -> bool:
@@ -333,7 +364,32 @@ def _point_segment_distance_sq(
     return (px - nearest_x) ** 2 + (py - nearest_y) ** 2
 
 
-def rect_polygon_collision(
+def _line_of_sight_clear(
+    start: tuple[float, float],
+    end: tuple[float, float],
+    walls: list["Wall"],
+) -> bool:
+    min_x = min(start[0], end[0])
+    min_y = min(start[1], end[1])
+    max_x = max(start[0], end[0])
+    max_y = max(start[1], end[1])
+    check_rect = pygame.Rect(
+        int(min_x),
+        int(min_y),
+        max(1, int(max_x - min_x)),
+        max(1, int(max_y - min_y)),
+    )
+    start_point = (int(start[0]), int(start[1]))
+    end_point = (int(end[0]), int(end[1]))
+    for wall in walls:
+        if not wall.rect.colliderect(check_rect):
+            continue
+        if wall.rect.clipline(start_point, end_point):
+            return False
+    return True
+
+
+def _rect_polygon_collision(
     rect_obj: rect.Rect, polygon: Sequence[tuple[float, float]]
 ) -> bool:
     min_x = min(p[0] for p in polygon)
@@ -372,7 +428,7 @@ def rect_polygon_collision(
     return False
 
 
-def circle_polygon_collision(
+def _circle_polygon_collision(
     center: tuple[float, float],
     radius: float,
     polygon: Sequence[tuple[float, float]],
@@ -388,12 +444,12 @@ def circle_polygon_collision(
     return False
 
 
-def collide_sprite_wall(
+def _collide_sprite_wall(
     sprite: pygame.sprite.Sprite, wall: pygame.sprite.Sprite
 ) -> bool:
     if hasattr(sprite, "radius"):
         center = sprite.rect.center
-        radius = float(getattr(sprite, "radius"))
+        radius = float(sprite.radius)
         if hasattr(wall, "_collides_circle"):
             return wall._collides_circle(center, radius)
         return _circle_rect_collision(center, radius, wall.rect)
@@ -413,10 +469,13 @@ def _spritecollide_walls(
     cell_size: int | None = None,
     grid_cols: int | None = None,
     grid_rows: int | None = None,
-) -> list[pygame.sprite.Sprite]:
+) -> list[Wall]:
     if wall_index is None:
-        return pygame.sprite.spritecollide(
-            sprite, walls, dokill, collided=collide_sprite_wall
+        return cast(
+            list[Wall],
+            pygame.sprite.spritecollide(
+                sprite, walls, dokill, collided=_collide_sprite_wall
+            ),
         )
     if cell_size is None:
         raise ValueError("cell_size is required when using wall_index")
@@ -429,7 +488,7 @@ def _spritecollide_walls(
     )
     if not candidates:
         return []
-    hit_list = [wall for wall in candidates if collide_sprite_wall(sprite, wall)]
+    hit_list = [wall for wall in candidates if _collide_sprite_wall(sprite, wall)]
     if dokill:
         for wall in hit_list:
             wall.kill()
@@ -444,10 +503,13 @@ def spritecollideany_walls(
     cell_size: int | None = None,
     grid_cols: int | None = None,
     grid_rows: int | None = None,
-) -> pygame.sprite.Sprite | None:
+) -> Wall | None:
     if wall_index is None:
-        return pygame.sprite.spritecollideany(
-            sprite, walls, collided=collide_sprite_wall
+        return cast(
+            Wall | None,
+            pygame.sprite.spritecollideany(
+                sprite, walls, collided=_collide_sprite_wall
+            ),
         )
     if cell_size is None:
         raise ValueError("cell_size is required when using wall_index")
@@ -458,7 +520,7 @@ def spritecollideany_walls(
         grid_cols=grid_cols,
         grid_rows=grid_rows,
     ):
-        if collide_sprite_wall(sprite, wall):
+        if _collide_sprite_wall(sprite, wall):
             return wall
     return None
 
@@ -473,150 +535,6 @@ def _circle_wall_collision(
     return _circle_rect_collision(center, radius, wall.rect)
 
 
-class Wall(pygame.sprite.Sprite):
-    def __init__(
-        self: Self,
-        x: int,
-        y: int,
-        width: int,
-        height: int,
-        *,
-        health: int = INTERNAL_WALL_HEALTH,
-        palette: EnvironmentPalette | None = None,
-        palette_category: str = "inner_wall",
-        bevel_depth: int = INTERNAL_WALL_BEVEL_DEPTH,
-        bevel_mask: tuple[bool, bool, bool, bool] | None = None,
-        draw_bottom_side: bool = False,
-        bottom_side_ratio: float = 0.1,
-        side_shade_ratio: float = 0.9,
-        on_destroy: Callable[[Self], None] | None = None,
-    ) -> None:
-        super().__init__()
-        safe_width = max(1, width)
-        safe_height = max(1, height)
-        self.image = pygame.Surface((safe_width, safe_height), pygame.SRCALPHA)
-        self.palette = palette
-        self.palette_category = palette_category
-        self.health = health
-        self.max_health = max(1, health)
-        self.on_destroy = on_destroy
-        self.bevel_depth = max(0, bevel_depth)
-        self.bevel_mask = bevel_mask or (False, False, False, False)
-        self.draw_bottom_side = draw_bottom_side
-        self.bottom_side_ratio = max(0.0, bottom_side_ratio)
-        self.side_shade_ratio = max(0.0, min(1.0, side_shade_ratio))
-        self._local_polygon = _build_beveled_polygon(
-            safe_width, safe_height, self.bevel_depth, self.bevel_mask
-        )
-        self._update_color()
-        self.rect = self.image.get_rect(topleft=(x, y))
-        # Keep collision rectangular even when beveled visually.
-        self._collision_polygon = None
-
-    def _take_damage(self: Self, *, amount: int = 1) -> None:
-        if self.health > 0:
-            self.health -= amount
-            self._update_color()
-            if self.health <= 0:
-                if self.on_destroy:
-                    try:
-                        self.on_destroy(self)
-                    except Exception as exc:
-                        print(f"Wall destroy callback failed: {exc}")
-                self.kill()
-
-    def _update_color(self: Self) -> None:
-        if self.health <= 0:
-            health_ratio = 0.0
-        else:
-            health_ratio = max(0.0, self.health / self.max_health)
-        fill_color, border_color = resolve_wall_colors(
-            health_ratio=health_ratio,
-            palette_category=self.palette_category,
-            palette=self.palette,
-        )
-        paint_wall_surface(
-            self.image,
-            fill_color=fill_color,
-            border_color=border_color,
-            bevel_depth=self.bevel_depth,
-            bevel_mask=self.bevel_mask,
-            draw_bottom_side=self.draw_bottom_side,
-            bottom_side_ratio=self.bottom_side_ratio,
-            side_shade_ratio=self.side_shade_ratio,
-        )
-
-    def collides_rect(self: Self, rect_obj: rect.Rect) -> bool:
-        if self._collision_polygon is None:
-            return self.rect.colliderect(rect_obj)
-        return rect_polygon_collision(rect_obj, self._collision_polygon)
-
-    def _collides_circle(
-        self: Self, center: tuple[float, float], radius: float
-    ) -> bool:
-        if not _circle_rect_collision(center, radius, self.rect):
-            return False
-        if self._collision_polygon is None:
-            return True
-        return circle_polygon_collision(center, radius, self._collision_polygon)
-
-    def set_palette(
-        self: Self, palette: EnvironmentPalette | None, *, force: bool = False
-    ) -> None:
-        """Update the wall's palette to match the current ambient palette."""
-
-        if not force and self.palette is palette:
-            return
-        self.palette = palette
-        self._update_color()
-
-
-class SteelBeam(pygame.sprite.Sprite):
-    """Single-cell obstacle that behaves like a tougher internal wall."""
-
-    def __init__(
-        self: Self,
-        x: int,
-        y: int,
-        size: int,
-        *,
-        health: int = STEEL_BEAM_HEALTH,
-        palette: EnvironmentPalette | None = None,
-    ) -> None:
-        super().__init__()
-        # Slightly inset from the cell size so it reads as a separate object.
-        margin = max(3, size // 14)
-        inset_size = max(4, size - margin * 2)
-        self.image = pygame.Surface((inset_size, inset_size), pygame.SRCALPHA)
-        self.health = health
-        self.max_health = max(1, health)
-        self.palette = palette
-        self._update_color()
-        self.rect = self.image.get_rect(center=(x + size // 2, y + size // 2))
-
-    def _take_damage(self: Self, *, amount: int = 1) -> None:
-        if self.health > 0:
-            self.health -= amount
-            self._update_color()
-            if self.health <= 0:
-                self.kill()
-
-    def _update_color(self: Self) -> None:
-        """Render a simple square with crossed diagonals that darkens as damaged."""
-        if self.health <= 0:
-            return
-        health_ratio = max(0, self.health / self.max_health)
-        base_color, line_color = resolve_steel_beam_colors(
-            health_ratio=health_ratio, palette=self.palette
-        )
-        paint_steel_beam_surface(
-            self.image,
-            base_color=base_color,
-            line_color=line_color,
-            health_ratio=health_ratio,
-        )
-
-
 class Camera:
     def __init__(self: Self, width: int, height: int) -> None:
         self.camera = pygame.Rect(0, 0, width, height)
@@ -915,7 +833,7 @@ def _zombie_tracker_movement(
     zombie: Zombie,
     player_center: tuple[int, int],
     walls: list[Wall],
-    footprints: list[dict[str, object]],
+    footprints: list[Footprint],
     cell_size: int,
     grid_cols: int,
     grid_rows: int,
@@ -923,9 +841,9 @@ def _zombie_tracker_movement(
 ) -> tuple[float, float]:
     is_in_sight = zombie._update_mode(player_center, ZOMBIE_TRACKER_SIGHT_RANGE)
     if not is_in_sight:
-        _zombie_update_tracker_target(zombie, footprints)
+        _zombie_update_tracker_target(zombie, footprints, walls)
         if zombie.tracker_target_pos is not None:
-            return zombie_move_toward(zombie, zombie.tracker_target_pos)
+            return _zombie_move_toward(zombie, zombie.tracker_target_pos)
         return _zombie_wander_move(
             zombie,
             walls,
@@ -934,14 +852,14 @@ def _zombie_tracker_movement(
             grid_rows=grid_rows,
             outer_wall_cells=outer_wall_cells,
         )
-    return zombie_move_toward(zombie, player_center)
+    return _zombie_move_toward(zombie, player_center)
 
 
-def zombie_wander_movement(
+def _zombie_wander_movement(
     zombie: Zombie,
     _player_center: tuple[int, int],
     walls: list[Wall],
-    _footprints: list[dict[str, object]],
+    _footprints: list[Footprint],
     cell_size: int,
     grid_cols: int,
     grid_rows: int,
@@ -957,7 +875,7 @@ def zombie_wander_movement(
     )
 
 
-def zombie_wall_follow_has_wall(
+def _zombie_wall_follow_has_wall(
     zombie: Zombie,
     walls: list[Wall],
     angle: float,
@@ -1013,7 +931,7 @@ def _zombie_wall_follow_movement(
     zombie: Zombie,
     player_center: tuple[int, int],
     walls: list[Wall],
-    _footprints: list[dict[str, object]],
+    _footprints: list[Footprint],
     cell_size: int,
     grid_cols: int,
     grid_rows: int,
@@ -1053,7 +971,7 @@ def _zombie_wall_follow_movement(
             zombie.wall_follow_last_side_has_wall = left_wall or right_wall
         else:
             if is_in_sight:
-                return zombie_move_toward(zombie, player_center)
+                return _zombie_move_toward(zombie, player_center)
             return _zombie_wander_move(
                 zombie,
                 walls,
@@ -1080,7 +998,7 @@ def _zombie_wall_follow_movement(
         and now - zombie.wall_follow_last_wall_time <= ZOMBIE_WALL_FOLLOW_LOST_WALL_MS
     )
     if is_in_sight:
-        return zombie_move_toward(zombie, player_center)
+        return _zombie_move_toward(zombie, player_center)
 
     turn_step = math.radians(5)
     if side_has_wall or forward_has_wall:
@@ -1113,11 +1031,11 @@ def _zombie_wall_follow_movement(
     return move_x, move_y
 
 
-def zombie_normal_movement(
+def _zombie_normal_movement(
     zombie: Zombie,
     player_center: tuple[int, int],
     walls: list[Wall],
-    _footprints: list[dict[str, object]],
+    _footprints: list[Footprint],
     cell_size: int,
     grid_cols: int,
     grid_rows: int,
@@ -1133,38 +1051,72 @@ def zombie_normal_movement(
             grid_rows=grid_rows,
             outer_wall_cells=outer_wall_cells,
         )
-    return zombie_move_toward(zombie, player_center)
+    return _zombie_move_toward(zombie, player_center)
 
 
 def _zombie_update_tracker_target(
-    zombie: Zombie, footprints: list[dict[str, object]]
+    zombie: Zombie,
+    footprints: list[Footprint],
+    walls: list[Wall],
 ) -> None:
-    zombie.tracker_target_pos = None
+    now = pygame.time.get_ticks()
+    if now - zombie.tracker_last_scan_time < zombie.tracker_scan_interval_ms:
+        return
+    zombie.tracker_last_scan_time = now
     if not footprints:
+        zombie.tracker_target_pos = None
         return
-    nearby: list[dict[str, object]] = []
+    nearby: list[Footprint] = []
+    last_target_time = zombie.tracker_target_time
+    scan_radius = ZOMBIE_TRACKER_SCENT_RADIUS * ZOMBIE_TRACKER_SCAN_RADIUS_MULTIPLIER
+    scent_radius_sq = scan_radius * scan_radius
+    min_target_dist_sq = (FOOTPRINT_STEP_DISTANCE * 0.5) ** 2
     for fp in footprints:
-        pos = fp.get("pos")
-        if not isinstance(pos, tuple):
-            continue
+        pos = fp.pos
+        fp_time = fp.time
         dx = pos[0] - zombie.x
         dy = pos[1] - zombie.y
-        if (
-            dx * dx + dy * dy
-            <= ZOMBIE_TRACKER_SCENT_RADIUS * ZOMBIE_TRACKER_SCENT_RADIUS
-        ):
+        if dx * dx + dy * dy <= min_target_dist_sq:
+            continue
+        if dx * dx + dy * dy <= scent_radius_sq:
             nearby.append(fp)
 
     if not nearby:
         return
 
-    latest = max(
-        nearby,
-        key=lambda fp: fp.get("time", -1) if isinstance(fp.get("time"), int) else -1,
-    )
-    pos = latest.get("pos")
-    if isinstance(pos, tuple):
-        zombie.tracker_target_pos = pos
+    nearby.sort(key=lambda fp: fp.time, reverse=True)
+    if last_target_time is not None:
+        newer = [fp for fp in nearby if fp.time > last_target_time]
+    else:
+        newer = nearby
+
+    for fp in newer[:ZOMBIE_TRACKER_SCENT_TOP_K]:
+        pos = fp.pos
+        fp_time = fp.time
+        if _line_of_sight_clear((zombie.x, zombie.y), pos, walls):
+            zombie.tracker_target_pos = pos
+            zombie.tracker_target_time = fp_time
+            return
+
+    if (
+        zombie.tracker_target_pos is not None
+        and (zombie.x - zombie.tracker_target_pos[0]) ** 2
+        + (zombie.y - zombie.tracker_target_pos[1]) ** 2
+        > min_target_dist_sq
+    ):
+        return
+
+    if last_target_time is None:
+        return
+
+    candidates = [fp for fp in nearby if fp.time > last_target_time]
+    if not candidates:
+        return
+    candidates.sort(key=lambda fp: fp.time)
+    next_fp = candidates[0]
+    zombie.tracker_target_pos = next_fp.pos
+    zombie.tracker_target_time = next_fp.time
+    return
 
 
 def _zombie_wander_move(
@@ -1177,16 +1129,30 @@ def _zombie_wander_move(
     outer_wall_cells: set[tuple[int, int]] | None,
 ) -> tuple[float, float]:
     now = pygame.time.get_ticks()
+    changed_angle = False
     if now - zombie.last_wander_change_time > zombie.wander_change_interval:
         zombie.wander_angle = RNG.uniform(0, math.tau)
         zombie.last_wander_change_time = now
         jitter = RNG.randint(-500, 500)
         zombie.wander_change_interval = max(0, zombie.wander_interval_ms + jitter)
+        changed_angle = True
 
     cell_x = int(zombie.x // cell_size)
     cell_y = int(zombie.y // cell_size)
     at_x_edge = cell_x in (0, grid_cols - 1)
     at_y_edge = cell_y in (0, grid_rows - 1)
+    if changed_angle and (at_x_edge or at_y_edge):
+        cos_angle = math.cos(zombie.wander_angle)
+        sin_angle = math.sin(zombie.wander_angle)
+        outward = (
+            (cell_x == 0 and cos_angle < 0)
+            or (cell_x == grid_cols - 1 and cos_angle > 0)
+            or (cell_y == 0 and sin_angle < 0)
+            or (cell_y == grid_rows - 1 and sin_angle > 0)
+        )
+        if outward:
+            if RNG.random() < 0.5:
+                zombie.wander_angle = (zombie.wander_angle + math.pi) % math.tau
 
     if at_x_edge or at_y_edge:
         if outer_wall_cells is not None:
@@ -1195,13 +1161,13 @@ def _zombie_wander_move(
                 if inward_cell not in outer_wall_cells:
                     target_x = (inward_cell[0] + 0.5) * cell_size
                     target_y = (inward_cell[1] + 0.5) * cell_size
-                    return zombie_move_toward(zombie, (target_x, target_y))
+                    return _zombie_move_toward(zombie, (target_x, target_y))
             if at_y_edge:
                 inward_cell = (cell_x, 1) if cell_y == 0 else (cell_x, grid_rows - 2)
                 if inward_cell not in outer_wall_cells:
                     target_x = (inward_cell[0] + 0.5) * cell_size
                     target_y = (inward_cell[1] + 0.5) * cell_size
-                    return zombie_move_toward(zombie, (target_x, target_y))
+                    return _zombie_move_toward(zombie, (target_x, target_y))
         else:
 
             def path_clear(next_x: float, next_y: float) -> bool:
@@ -1224,19 +1190,13 @@ def _zombie_wander_move(
                 inward_dy = zombie.speed if cell_y == 0 else -zombie.speed
                 if path_clear(zombie.x, zombie.y + inward_dy):
                     return 0.0, inward_dy
-        # if at_x_edge:
-        #     direction = 1.0 if math.sin(zombie.wander_angle) >= 0 else -1.0
-        #     return 0.0, direction * zombie.speed
-        # if at_y_edge:
-        #     direction = 1.0 if math.cos(zombie.wander_angle) >= 0 else -1.0
-        #     return direction * zombie.speed, 0.0
 
     move_x = math.cos(zombie.wander_angle) * zombie.speed
     move_y = math.sin(zombie.wander_angle) * zombie.speed
     return move_x, move_y
 
 
-def zombie_move_toward(
+def _zombie_move_toward(
     zombie: Zombie, target: tuple[float, float]
 ) -> tuple[float, float]:
     dx = target[0] - zombie.x
@@ -1285,9 +1245,12 @@ class Zombie(pygame.sprite.Sprite):
             elif wall_follower:
                 movement_strategy = _zombie_wall_follow_movement
             else:
-                movement_strategy = zombie_normal_movement
+                movement_strategy = _zombie_normal_movement
         self.movement_strategy = movement_strategy
         self.tracker_target_pos: tuple[float, float] | None = None
+        self.tracker_target_time: int | None = None
+        self.tracker_last_scan_time = 0
+        self.tracker_scan_interval_ms = ZOMBIE_TRACKER_SCAN_INTERVAL_MS
         self.wall_follow_side = RNG.choice([-1.0, 1.0]) if wall_follower else 0.0
         self.wall_follow_angle = RNG.uniform(0, math.tau) if wall_follower else None
         self.wall_follow_last_wall_time: int | None = None
@@ -1384,7 +1347,7 @@ class Zombie(pygame.sprite.Sprite):
             return move_x, move_y
 
         if self.wall_follower:
-            other_radius = float(getattr(closest, "radius", self.radius))
+            other_radius = float(closest.radius)
             bump_dist_sq = (self.radius + other_radius) ** 2
             if closest_dist_sq < bump_dist_sq and RNG.random() < 0.1:
                 if self.wall_follow_angle is None:
@@ -1442,7 +1405,7 @@ class Zombie(pygame.sprite.Sprite):
         player_center: tuple[int, int],
         walls: list[Wall],
         nearby_zombies: Iterable[Zombie],
-        footprints: list[dict[str, object]] | None = None,
+        footprints: list[Footprint] | None = None,
         *,
         cell_size: int,
         grid_cols: int,