zombie-escape 1.12.3__py3-none-any.whl → 1.13.1__py3-none-any.whl

zombie_escape/entities.py

@@ -30,6 +30,9 @@ from .entities_constants import (
     HUMANOID_WALL_BUMP_FRAMES,
     INTERNAL_WALL_BEVEL_DEPTH,
     INTERNAL_WALL_HEALTH,
+    JUMP_DURATION_MS,
+    JUMP_SCALE_MAX,
+    PLAYER_JUMP_RANGE,
     PLAYER_RADIUS,
     PLAYER_SPEED,
     PLAYER_WALL_DAMAGE,
@@ -38,6 +41,7 @@ from .entities_constants import (
     STEEL_BEAM_HEALTH,
     SURVIVOR_APPROACH_RADIUS,
     SURVIVOR_APPROACH_SPEED,
+    SURVIVOR_JUMP_RANGE,
     SURVIVOR_RADIUS,
     ZOMBIE_AGING_DURATION_FRAMES,
     ZOMBIE_AGING_MIN_SPEED_RATIO,
@@ -45,23 +49,27 @@ from .entities_constants import (
     ZOMBIE_SEPARATION_DISTANCE,
     ZOMBIE_SIGHT_RANGE,
     ZOMBIE_SPEED,
+    ZOMBIE_TRACKER_FAR_SCENT_RADIUS,
+    ZOMBIE_TRACKER_CROWD_BAND_LENGTH,
+    ZOMBIE_TRACKER_CROWD_BAND_WIDTH,
+    ZOMBIE_TRACKER_CROWD_COUNT,
+    ZOMBIE_TRACKER_NEWER_FOOTPRINT_MS,
+    ZOMBIE_TRACKER_RELOCK_DELAY_MS,
     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,
-    ZOMBIE_WALL_FOLLOW_LOST_WALL_MS,
-    ZOMBIE_WALL_FOLLOW_PROBE_ANGLE_DEG,
-    ZOMBIE_WALL_FOLLOW_PROBE_STEP,
-    ZOMBIE_WALL_FOLLOW_SENSOR_DISTANCE,
-    ZOMBIE_WALL_FOLLOW_TARGET_GAP,
+    ZOMBIE_WALL_HUG_LOST_WALL_MS,
+    ZOMBIE_WALL_HUG_PROBE_ANGLE_DEG,
+    ZOMBIE_WALL_HUG_PROBE_STEP,
+    ZOMBIE_WALL_HUG_SENSOR_DISTANCE,
+    ZOMBIE_WALL_HUG_TARGET_GAP,
     ZOMBIE_WANDER_INTERVAL_MS,
 )
 from .gameplay.constants import FOOTPRINT_STEP_DISTANCE
 from .models import Footprint
-from .render_constants import ANGLE_BINS, ZOMBIE_NOSE_COLOR
 from .render_assets import (
     EnvironmentPalette,
     angle_bin_from_vector,
@@ -71,6 +79,7 @@ from .render_assets import (
     build_flashlight_surface,
     build_fuel_can_surface,
     build_player_directional_surfaces,
+    build_rubble_wall_surface,
     build_shoes_surface,
     build_survivor_directional_surfaces,
     build_zombie_directional_surfaces,
@@ -79,10 +88,13 @@ from .render_assets import (
     paint_car_surface,
     paint_steel_beam_surface,
     paint_wall_surface,
+    rubble_offset_for_size,
     resolve_car_color,
     resolve_steel_beam_colors,
     resolve_wall_colors,
+    RUBBLE_ROTATION_DEG,
 )
+from .render_constants import ANGLE_BINS, ZOMBIE_NOSE_COLOR
 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
@@ -90,6 +102,31 @@ from .world_grid import WallIndex, apply_tile_edge_nudge, walls_for_radius
 RNG = get_rng()
 
 
+def _can_humanoid_jump(
+    x: float,
+    y: float,
+    dx: float,
+    dy: float,
+    jump_range: float,
+    cell_size: int,
+    walkable_cells: Iterable[tuple[int, int]],
+) -> bool:
+    """Accurately check if a jump is possible in the given movement direction."""
+    move_len = math.hypot(dx, dy)
+    if move_len <= 0:
+        return False
+    look_ahead_x = x + (dx / move_len) * jump_range
+    look_ahead_y = y + (dy / move_len) * jump_range
+    lax, lay = int(look_ahead_x // cell_size), int(look_ahead_y // cell_size)
+    return (lax, lay) in walkable_cells
+
+
+def _get_jump_scale(elapsed_ms: int, duration_ms: int, scale_max: float) -> float:
+    """Calculate the parabolic scale factor for a jump."""
+    t = max(0.0, min(1.0, elapsed_ms / duration_ms))
+    return 1.0 + scale_max * (4 * t * (1 - t))
+
+
 class Wall(pygame.sprite.Sprite):
     def __init__(
         self: Self,
@@ -188,6 +225,67 @@ class Wall(pygame.sprite.Sprite):
         self._update_color()
 
 
+class RubbleWall(Wall):
+    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,
+        rubble_rotation_deg: float | None = None,
+        rubble_offset_px: int | None = None,
+        on_destroy: Callable[[Self], None] | None = None,
+    ) -> None:
+        self._rubble_rotation_deg = (
+            RUBBLE_ROTATION_DEG if rubble_rotation_deg is None else rubble_rotation_deg
+        )
+        base_size = max(1, min(width, height))
+        self._rubble_offset_px = (
+            rubble_offset_for_size(base_size)
+            if rubble_offset_px is None
+            else rubble_offset_px
+        )
+        super().__init__(
+            x,
+            y,
+            width,
+            height,
+            health=health,
+            palette=palette,
+            palette_category=palette_category,
+            bevel_depth=bevel_depth,
+            bevel_mask=(False, False, False, False),
+            draw_bottom_side=False,
+            on_destroy=on_destroy,
+        )
+
+    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,
+        )
+        rubble_surface = build_rubble_wall_surface(
+            self.image.get_width(),
+            fill_color=fill_color,
+            border_color=border_color,
+            angle_deg=self._rubble_rotation_deg,
+            offset_px=self._rubble_offset_px,
+            bevel_depth=self.bevel_depth,
+        )
+        self.image.fill((0, 0, 0, 0))
+        self.image.blit(rubble_surface, (0, 0))
+
+
 class SteelBeam(pygame.sprite.Sprite):
     """Single-cell obstacle that behaves like a tougher internal wall."""
 
@@ -248,6 +346,7 @@ MovementStrategy = Callable[
         "Zombie",
         tuple[int, int],
         list[Wall],
+        Iterable["Zombie"],
         list[Footprint],
         int,
         int,
@@ -596,6 +695,9 @@ class Player(pygame.sprite.Sprite):
         self.in_car = False
         self.x = float(self.rect.centerx)
         self.y = float(self.rect.centery)
+        self.jump_start_at = 0
+        self.jump_duration = JUMP_DURATION_MS
+        self.is_jumping = False
 
     def move(
         self: Self,
@@ -607,6 +709,8 @@ class Player(pygame.sprite.Sprite):
         cell_size: int | None = None,
         level_width: int | None = None,
         level_height: int | None = None,
+        pitfall_cells: set[tuple[int, int]] | None = None,
+        walkable_cells: list[tuple[int, int]] | None = None,
     ) -> None:
         if self.in_car:
             return
@@ -614,6 +718,28 @@ class Player(pygame.sprite.Sprite):
         if level_width is None or level_height is None:
             raise ValueError("level_width/level_height are required for movement")
 
+        now = pygame.time.get_ticks()
+        if self.is_jumping:
+            elapsed = now - self.jump_start_at
+            if elapsed >= self.jump_duration:
+                self.is_jumping = False
+                self._update_image_scale(1.0)
+            else:
+                self._update_image_scale(
+                    _get_jump_scale(elapsed, self.jump_duration, JUMP_SCALE_MAX)
+                )
+
+        # Pre-calculate jump possibility based on actual movement vector
+        can_jump_now = (
+            not self.is_jumping
+            and pitfall_cells
+            and cell_size
+            and walkable_cells
+            and _can_humanoid_jump(
+                self.x, self.y, dx, dy, PLAYER_JUMP_RANGE, cell_size, walkable_cells
+            )
+        )
+
         inner_wall_hit = False
         inner_wall_cell: tuple[int, int] | None = None
 
@@ -627,18 +753,32 @@ class Player(pygame.sprite.Sprite):
                 wall_index=wall_index,
                 cell_size=cell_size,
             )
-            if hit_list_x:
-                damage = max(1, PLAYER_WALL_DAMAGE // len(hit_list_x))
-                for wall in hit_list_x:
-                    if wall.alive():
-                        wall._take_damage(amount=damage)
-                        if _is_inner_wall(wall):
-                            inner_wall_hit = True
-                            if inner_wall_cell is None and cell_size:
-                                inner_wall_cell = (
-                                    int(wall.rect.centerx // cell_size),
-                                    int(wall.rect.centery // cell_size),
-                                )
+            blocked_by_pitfall = False
+            if not self.is_jumping and pitfall_cells and cell_size:
+                cx, cy = (
+                    int(self.rect.centerx // cell_size),
+                    int(self.rect.centery // cell_size),
+                )
+                if (cx, cy) in pitfall_cells:
+                    if can_jump_now:
+                        self.is_jumping = True
+                        self.jump_start_at = now
+                    else:
+                        blocked_by_pitfall = True
+
+            if hit_list_x or blocked_by_pitfall:
+                if hit_list_x:
+                    damage = max(1, PLAYER_WALL_DAMAGE // len(hit_list_x))
+                    for wall in hit_list_x:
+                        if wall.alive():
+                            wall._take_damage(amount=damage)
+                            if _is_inner_wall(wall):
+                                inner_wall_hit = True
+                                if inner_wall_cell is None and cell_size:
+                                    inner_wall_cell = (
+                                        int(wall.rect.centerx // cell_size),
+                                        int(wall.rect.centery // cell_size),
+                                    )
                 self.x -= dx * 1.5
                 self.rect.centerx = int(self.x)
 
@@ -652,18 +792,32 @@ class Player(pygame.sprite.Sprite):
                 wall_index=wall_index,
                 cell_size=cell_size,
             )
-            if hit_list_y:
-                damage = max(1, PLAYER_WALL_DAMAGE // len(hit_list_y))
-                for wall in hit_list_y:
-                    if wall.alive():
-                        wall._take_damage(amount=damage)
-                        if _is_inner_wall(wall):
-                            inner_wall_hit = True
-                            if inner_wall_cell is None and cell_size:
-                                inner_wall_cell = (
-                                    int(wall.rect.centerx // cell_size),
-                                    int(wall.rect.centery // cell_size),
-                                )
+            blocked_by_pitfall = False
+            if not self.is_jumping and pitfall_cells and cell_size:
+                cx, cy = (
+                    int(self.rect.centerx // cell_size),
+                    int(self.rect.centery // cell_size),
+                )
+                if (cx, cy) in pitfall_cells:
+                    if can_jump_now:
+                        self.is_jumping = True
+                        self.jump_start_at = now
+                    else:
+                        blocked_by_pitfall = True
+
+            if hit_list_y or blocked_by_pitfall:
+                if hit_list_y:
+                    damage = max(1, PLAYER_WALL_DAMAGE // len(hit_list_y))
+                    for wall in hit_list_y:
+                        if wall.alive():
+                            wall._take_damage(amount=damage)
+                            if _is_inner_wall(wall):
+                                inner_wall_hit = True
+                                if inner_wall_cell is None and cell_size:
+                                    inner_wall_cell = (
+                                        int(wall.rect.centerx // cell_size),
+                                        int(wall.rect.centery // cell_size),
+                                    )
                 self.y -= dy * 1.5
                 self.rect.centery = int(self.y)
 
@@ -672,6 +826,19 @@ class Player(pygame.sprite.Sprite):
         self.inner_wall_cell = inner_wall_cell
         self._update_facing_for_bump(inner_wall_hit)
 
+    def _update_image_scale(self: Self, scale: float) -> None:
+        """Apply scaling to the current directional image."""
+        base_img = self.directional_images[self.facing_bin]
+        if scale == 1.0:
+            self.image = base_img
+        else:
+            w, h = base_img.get_size()
+            self.image = pygame.transform.scale(
+                base_img, (int(w * scale), int(h * scale))
+            )
+        old_center = self.rect.center
+        self.rect = self.image.get_rect(center=old_center)
+
     def update_facing_from_input(self: Self, dx: float, dy: float) -> None:
         if self.in_car:
             return
@@ -732,6 +899,9 @@ class Survivor(pygame.sprite.Sprite):
         self.y = float(self.rect.centery)
         self.following = False
         self.rescued = False
+        self.jump_start_at = 0
+        self.jump_duration = JUMP_DURATION_MS
+        self.is_jumping = False
 
     def set_following(self: Self) -> None:
         if self.is_buddy and not self.rescued:
@@ -757,6 +927,8 @@ class Survivor(pygame.sprite.Sprite):
         wall_index: WallIndex | None = None,
         cell_size: int | None = None,
         wall_cells: set[tuple[int, int]] | None = None,
+        pitfall_cells: set[tuple[int, int]] | None = None,
+        walkable_cells: list[tuple[int, int]] | None = None,
         bevel_corners: dict[tuple[int, int], tuple[bool, bool, bool, bool]]
         | None = None,
         grid_cols: int | None = None,
@@ -767,6 +939,18 @@ class Survivor(pygame.sprite.Sprite):
     ) -> None:
         if level_width is None or level_height is None:
             raise ValueError("level_width/level_height are required for movement")
+
+        now = pygame.time.get_ticks()
+        if self.is_jumping:
+            elapsed = now - self.jump_start_at
+            if elapsed >= self.jump_duration:
+                self.is_jumping = False
+                self._update_image_scale(1.0)
+            else:
+                self._update_image_scale(
+                    _get_jump_scale(elapsed, self.jump_duration, JUMP_SCALE_MAX)
+                )
+
         if self.is_buddy:
             if self.rescued or not self.following:
                 self.rect.center = (int(self.x), int(self.y))
@@ -812,36 +996,82 @@ class Survivor(pygame.sprite.Sprite):
             self._update_input_facing(move_x, move_y)
             inner_wall_hit = False
 
+            # Pre-calculate jump possibility for Buddy
+            can_jump_now = (
+                not self.is_jumping
+                and pitfall_cells
+                and cell_size
+                and walkable_cells
+                and _can_humanoid_jump(
+                    self.x,
+                    self.y,
+                    move_x,
+                    move_y,
+                    SURVIVOR_JUMP_RANGE,
+                    cell_size,
+                    walkable_cells,
+                )
+            )
+
             if move_x:
                 self.x += move_x
                 self.rect.centerx = int(self.x)
-                wall = spritecollideany_walls(
+                hit_wall = spritecollideany_walls(
                     self,
                     walls,
                     wall_index=wall_index,
                     cell_size=cell_size,
                 )
-                if wall:
-                    if wall.alive():
-                        wall._take_damage(amount=max(1, BUDDY_WALL_DAMAGE))
-                    if _is_inner_wall(wall):
-                        inner_wall_hit = True
+                blocked_by_pitfall = False
+                if not self.is_jumping and pitfall_cells and cell_size:
+                    cx, cy = (
+                        int(self.rect.centerx // cell_size),
+                        int(self.rect.centery // cell_size),
+                    )
+                    if (cx, cy) in pitfall_cells:
+                        if can_jump_now:
+                            self.is_jumping = True
+                            self.jump_start_at = now
+                        else:
+                            blocked_by_pitfall = True
+
+                if hit_wall or blocked_by_pitfall:
+                    if hit_wall:
+                        if hit_wall.alive():
+                            hit_wall._take_damage(amount=max(1, BUDDY_WALL_DAMAGE))
+                        if _is_inner_wall(hit_wall):
+                            inner_wall_hit = True
                     self.x -= move_x
                     self.rect.centerx = int(self.x)
+
             if move_y:
                 self.y += move_y
                 self.rect.centery = int(self.y)
-                wall = spritecollideany_walls(
+                hit_wall = spritecollideany_walls(
                     self,
                     walls,
                     wall_index=wall_index,
                     cell_size=cell_size,
                 )
-                if wall:
-                    if wall.alive():
-                        wall._take_damage(amount=max(1, BUDDY_WALL_DAMAGE))
-                    if _is_inner_wall(wall):
-                        inner_wall_hit = True
+                blocked_by_pitfall = False
+                if not self.is_jumping and pitfall_cells and cell_size:
+                    cx, cy = (
+                        int(self.rect.centerx // cell_size),
+                        int(self.rect.centery // cell_size),
+                    )
+                    if (cx, cy) in pitfall_cells:
+                        if can_jump_now:
+                            self.is_jumping = True
+                            self.jump_start_at = now
+                        else:
+                            blocked_by_pitfall = True
+
+                if hit_wall or blocked_by_pitfall:
+                    if hit_wall:
+                        if hit_wall.alive():
+                            hit_wall._take_damage(amount=max(1, BUDDY_WALL_DAMAGE))
+                        if _is_inner_wall(hit_wall):
+                            inner_wall_hit = True
                     self.y -= move_y
                     self.rect.centery = int(self.y)
 
@@ -877,6 +1107,23 @@ class Survivor(pygame.sprite.Sprite):
 
         self._update_input_facing(move_x, move_y)
 
+        # Pre-calculate jump possibility for normal Survivor
+        can_jump_now = (
+            not self.is_jumping
+            and pitfall_cells
+            and cell_size
+            and walkable_cells
+            and _can_humanoid_jump(
+                self.x,
+                self.y,
+                move_x,
+                move_y,
+                SURVIVOR_JUMP_RANGE,
+                cell_size,
+                walkable_cells,
+            )
+        )
+
         if (
             cell_size is not None
             and wall_cells is not None
@@ -898,29 +1145,70 @@ class Survivor(pygame.sprite.Sprite):
         if move_x:
             self.x += move_x
             self.rect.centerx = int(self.x)
-            if spritecollideany_walls(
+            hit_by_wall = spritecollideany_walls(
                 self,
                 walls,
                 wall_index=wall_index,
                 cell_size=cell_size,
-            ):
+            )
+            blocked_by_pitfall = False
+            if not self.is_jumping and pitfall_cells and cell_size:
+                cx, cy = (
+                    int(self.rect.centerx // cell_size),
+                    int(self.rect.centery // cell_size),
+                )
+                if (cx, cy) in pitfall_cells:
+                    if can_jump_now:
+                        self.is_jumping = True
+                        self.jump_start_at = now
+                    else:
+                        blocked_by_pitfall = True
+
+            if hit_by_wall or blocked_by_pitfall:
                 self.x -= move_x
                 self.rect.centerx = int(self.x)
         if move_y:
             self.y += move_y
             self.rect.centery = int(self.y)
-            if spritecollideany_walls(
+            hit_by_wall = spritecollideany_walls(
                 self,
                 walls,
                 wall_index=wall_index,
                 cell_size=cell_size,
-            ):
+            )
+            blocked_by_pitfall = False
+            if not self.is_jumping and pitfall_cells and cell_size:
+                cx, cy = (
+                    int(self.rect.centerx // cell_size),
+                    int(self.rect.centery // cell_size),
+                )
+                if (cx, cy) in pitfall_cells:
+                    if can_jump_now:
+                        self.is_jumping = True
+                        self.jump_start_at = now
+                    else:
+                        blocked_by_pitfall = True
+
+            if hit_by_wall or blocked_by_pitfall:
                 self.y -= move_y
                 self.rect.centery = int(self.y)
 
         self.rect.center = (int(self.x), int(self.y))
         self._update_facing_for_bump(False)
 
+    def _update_image_scale(self: Self, scale: float) -> None:
+        """Apply scaling to the current directional image."""
+        base_img = self.directional_images[self.facing_bin]
+        if scale == 1.0:
+            self.image = base_img
+        else:
+            w, h = base_img.get_size()
+            self.image = pygame.transform.scale(
+                base_img, (int(w * scale), int(h * scale))
+            )
+        old_center = self.rect.center
+        self.rect = self.image.get_rect(center=old_center)
+
     def _update_input_facing(self: Self, dx: float, dy: float) -> None:
         new_bin = angle_bin_from_vector(dx, dy)
         if new_bin is None:
@@ -972,6 +1260,7 @@ def _zombie_tracker_movement(
     zombie: Zombie,
     player_center: tuple[int, int],
     walls: list[Wall],
+    nearby_zombies: Iterable[Zombie],
     footprints: list[Footprint],
     cell_size: int,
     grid_cols: int,
@@ -980,6 +1269,22 @@ def _zombie_tracker_movement(
 ) -> tuple[float, float]:
     is_in_sight = zombie._update_mode(player_center, ZOMBIE_TRACKER_SIGHT_RANGE)
     if not is_in_sight:
+        if _zombie_tracker_is_crowded(zombie, nearby_zombies):
+            last_target_time = zombie.tracker_target_time
+            if last_target_time is None:
+                last_target_time = pygame.time.get_ticks()
+            zombie.tracker_relock_after_time = (
+                last_target_time + ZOMBIE_TRACKER_RELOCK_DELAY_MS
+            )
+            zombie.tracker_target_pos = None
+            return _zombie_wander_move(
+                zombie,
+                walls,
+                cell_size=cell_size,
+                grid_cols=grid_cols,
+                grid_rows=grid_rows,
+                outer_wall_cells=outer_wall_cells,
+            )
         _zombie_update_tracker_target(zombie, footprints, walls)
         if zombie.tracker_target_pos is not None:
             return _zombie_move_toward(zombie, zombie.tracker_target_pos)
@@ -998,6 +1303,7 @@ def _zombie_wander_movement(
     zombie: Zombie,
     _player_center: tuple[int, int],
     walls: list[Wall],
+    _nearby_zombies: Iterable[Zombie],
     _footprints: list[Footprint],
     cell_size: int,
     grid_cols: int,
@@ -1014,7 +1320,7 @@ def _zombie_wander_movement(
     )
 
 
-def _zombie_wall_follow_has_wall(
+def _zombie_wall_hug_has_wall(
     zombie: Zombie,
     walls: list[Wall],
     angle: float,
@@ -1034,13 +1340,13 @@ def _zombie_wall_follow_has_wall(
     )
 
 
-def _zombie_wall_follow_wall_distance(
+def _zombie_wall_hug_wall_distance(
     zombie: Zombie,
     walls: list[Wall],
     angle: float,
     max_distance: float,
     *,
-    step: float = ZOMBIE_WALL_FOLLOW_PROBE_STEP,
+    step: float = ZOMBIE_WALL_HUG_PROBE_STEP,
 ) -> float:
     direction_x = math.cos(angle)
     direction_y = math.sin(angle)
@@ -1066,10 +1372,11 @@ def _zombie_wall_follow_wall_distance(
     return max_distance
 
 
-def _zombie_wall_follow_movement(
+def _zombie_wall_hug_movement(
     zombie: Zombie,
     player_center: tuple[int, int],
     walls: list[Wall],
+    _nearby_zombies: Iterable[Zombie],
     _footprints: list[Footprint],
     cell_size: int,
     grid_cols: int,
@@ -1077,21 +1384,21 @@ def _zombie_wall_follow_movement(
     outer_wall_cells: set[tuple[int, int]] | None,
 ) -> tuple[float, float]:
     is_in_sight = zombie._update_mode(player_center, ZOMBIE_TRACKER_SIGHT_RANGE)
-    if zombie.wall_follow_angle is None:
-        zombie.wall_follow_angle = zombie.wander_angle
-    if zombie.wall_follow_side == 0:
-        sensor_distance = ZOMBIE_WALL_FOLLOW_SENSOR_DISTANCE + zombie.radius
-        forward_angle = zombie.wall_follow_angle
-        probe_offset = math.radians(ZOMBIE_WALL_FOLLOW_PROBE_ANGLE_DEG)
+    if zombie.wall_hug_angle is None:
+        zombie.wall_hug_angle = zombie.wander_angle
+    if zombie.wall_hug_side == 0:
+        sensor_distance = ZOMBIE_WALL_HUG_SENSOR_DISTANCE + zombie.radius
+        forward_angle = zombie.wall_hug_angle
+        probe_offset = math.radians(ZOMBIE_WALL_HUG_PROBE_ANGLE_DEG)
         left_angle = forward_angle + probe_offset
         right_angle = forward_angle - probe_offset
-        left_dist = _zombie_wall_follow_wall_distance(
+        left_dist = _zombie_wall_hug_wall_distance(
             zombie, walls, left_angle, sensor_distance
         )
-        right_dist = _zombie_wall_follow_wall_distance(
+        right_dist = _zombie_wall_hug_wall_distance(
             zombie, walls, right_angle, sensor_distance
         )
-        forward_dist = _zombie_wall_follow_wall_distance(
+        forward_dist = _zombie_wall_hug_wall_distance(
             zombie, walls, forward_angle, sensor_distance
         )
         left_wall = left_dist < sensor_distance
@@ -1099,15 +1406,15 @@ def _zombie_wall_follow_movement(
         forward_wall = forward_dist < sensor_distance
         if left_wall or right_wall or forward_wall:
             if left_wall and not right_wall:
-                zombie.wall_follow_side = 1.0
+                zombie.wall_hug_side = 1.0
             elif right_wall and not left_wall:
-                zombie.wall_follow_side = -1.0
+                zombie.wall_hug_side = -1.0
             elif left_wall and right_wall:
-                zombie.wall_follow_side = 1.0 if left_dist <= right_dist else -1.0
+                zombie.wall_hug_side = 1.0 if left_dist <= right_dist else -1.0
             else:
-                zombie.wall_follow_side = RNG.choice([-1.0, 1.0])
-            zombie.wall_follow_last_wall_time = pygame.time.get_ticks()
-            zombie.wall_follow_last_side_has_wall = left_wall or right_wall
+                zombie.wall_hug_side = RNG.choice([-1.0, 1.0])
+            zombie.wall_hug_last_wall_time = pygame.time.get_ticks()
+            zombie.wall_hug_last_side_has_wall = left_wall or right_wall
         else:
             if is_in_sight:
                 return _zombie_move_toward(zombie, player_center)
@@ -1120,53 +1427,53 @@ def _zombie_wall_follow_movement(
                 outer_wall_cells=outer_wall_cells,
             )
 
-    sensor_distance = ZOMBIE_WALL_FOLLOW_SENSOR_DISTANCE + zombie.radius
-    probe_offset = math.radians(ZOMBIE_WALL_FOLLOW_PROBE_ANGLE_DEG)
-    side_angle = zombie.wall_follow_angle + zombie.wall_follow_side * probe_offset
-    side_dist = _zombie_wall_follow_wall_distance(
+    sensor_distance = ZOMBIE_WALL_HUG_SENSOR_DISTANCE + zombie.radius
+    probe_offset = math.radians(ZOMBIE_WALL_HUG_PROBE_ANGLE_DEG)
+    side_angle = zombie.wall_hug_angle + zombie.wall_hug_side * probe_offset
+    side_dist = _zombie_wall_hug_wall_distance(
         zombie, walls, side_angle, sensor_distance
     )
-    forward_dist = _zombie_wall_follow_wall_distance(
-        zombie, walls, zombie.wall_follow_angle, sensor_distance
+    forward_dist = _zombie_wall_hug_wall_distance(
+        zombie, walls, zombie.wall_hug_angle, sensor_distance
     )
     side_has_wall = side_dist < sensor_distance
     forward_has_wall = forward_dist < sensor_distance
     now = pygame.time.get_ticks()
     wall_recent = (
-        zombie.wall_follow_last_wall_time is not None
-        and now - zombie.wall_follow_last_wall_time <= ZOMBIE_WALL_FOLLOW_LOST_WALL_MS
+        zombie.wall_hug_last_wall_time is not None
+        and now - zombie.wall_hug_last_wall_time <= ZOMBIE_WALL_HUG_LOST_WALL_MS
     )
     if is_in_sight:
         return _zombie_move_toward(zombie, player_center)
 
     turn_step = math.radians(5)
     if side_has_wall or forward_has_wall:
-        zombie.wall_follow_last_wall_time = now
+        zombie.wall_hug_last_wall_time = now
     if side_has_wall:
-        zombie.wall_follow_last_side_has_wall = True
-        gap_error = ZOMBIE_WALL_FOLLOW_TARGET_GAP - side_dist
+        zombie.wall_hug_last_side_has_wall = True
+        gap_error = ZOMBIE_WALL_HUG_TARGET_GAP - side_dist
         if abs(gap_error) > 0.1:
-            ratio = min(1.0, abs(gap_error) / ZOMBIE_WALL_FOLLOW_TARGET_GAP)
+            ratio = min(1.0, abs(gap_error) / ZOMBIE_WALL_HUG_TARGET_GAP)
             turn = turn_step * ratio
             if gap_error > 0:
-                zombie.wall_follow_angle -= zombie.wall_follow_side * turn
+                zombie.wall_hug_angle -= zombie.wall_hug_side * turn
             else:
-                zombie.wall_follow_angle += zombie.wall_follow_side * turn
-        if forward_dist < ZOMBIE_WALL_FOLLOW_TARGET_GAP:
-            zombie.wall_follow_angle -= zombie.wall_follow_side * (turn_step * 1.5)
+                zombie.wall_hug_angle += zombie.wall_hug_side * turn
+        if forward_dist < ZOMBIE_WALL_HUG_TARGET_GAP:
+            zombie.wall_hug_angle -= zombie.wall_hug_side * (turn_step * 1.5)
     else:
-        zombie.wall_follow_last_side_has_wall = False
+        zombie.wall_hug_last_side_has_wall = False
         if forward_has_wall:
-            zombie.wall_follow_angle -= zombie.wall_follow_side * turn_step
+            zombie.wall_hug_angle -= zombie.wall_hug_side * turn_step
         elif wall_recent:
-            zombie.wall_follow_angle += zombie.wall_follow_side * (turn_step * 0.75)
+            zombie.wall_hug_angle += zombie.wall_hug_side * (turn_step * 0.75)
         else:
-            zombie.wall_follow_angle += zombie.wall_follow_side * (math.pi / 2.0)
-            zombie.wall_follow_side = 0.0
-    zombie.wall_follow_angle %= math.tau
+            zombie.wall_hug_angle += zombie.wall_hug_side * (math.pi / 2.0)
+            zombie.wall_hug_side = 0.0
+    zombie.wall_hug_angle %= math.tau
 
-    move_x = math.cos(zombie.wall_follow_angle) * zombie.speed
-    move_y = math.sin(zombie.wall_follow_angle) * zombie.speed
+    move_x = math.cos(zombie.wall_hug_angle) * zombie.speed
+    move_y = math.sin(zombie.wall_hug_angle) * zombie.speed
     return move_x, move_y
 
 
@@ -1174,6 +1481,7 @@ def _zombie_normal_movement(
     zombie: Zombie,
     player_center: tuple[int, int],
     walls: list[Wall],
+    _nearby_zombies: Iterable[Zombie],
     _footprints: list[Footprint],
     cell_size: int,
     grid_cols: int,
@@ -1207,12 +1515,29 @@ def _zombie_update_tracker_target(
         return
     nearby: list[Footprint] = []
     last_target_time = zombie.tracker_target_time
-    scan_radius = ZOMBIE_TRACKER_SCENT_RADIUS * ZOMBIE_TRACKER_SCAN_RADIUS_MULTIPLIER
+    far_radius_sq = ZOMBIE_TRACKER_FAR_SCENT_RADIUS * ZOMBIE_TRACKER_FAR_SCENT_RADIUS
+    latest_fp_time: int | None = None
+    relock_after = zombie.tracker_relock_after_time
+    for fp in footprints:
+        dx = fp.pos[0] - zombie.x
+        dy = fp.pos[1] - zombie.y
+        if dx * dx + dy * dy <= far_radius_sq:
+            if latest_fp_time is None or fp.time > latest_fp_time:
+                latest_fp_time = fp.time
+    use_far_scan = last_target_time is None or (
+        latest_fp_time is not None
+        and latest_fp_time - last_target_time >= ZOMBIE_TRACKER_NEWER_FOOTPRINT_MS
+    )
+    scan_radius = (
+        ZOMBIE_TRACKER_FAR_SCENT_RADIUS if use_far_scan else ZOMBIE_TRACKER_SCENT_RADIUS
+    )
     scent_radius_sq = scan_radius * scan_radius
     min_target_dist_sq = (FOOTPRINT_STEP_DISTANCE * 0.5) ** 2
     for fp in footprints:
         pos = fp.pos
         fp_time = fp.time
+        if relock_after is not None and fp_time < relock_after:
+            continue
         dx = pos[0] - zombie.x
         dy = pos[1] - zombie.y
         if dx * dx + dy * dy <= min_target_dist_sq:
@@ -1235,6 +1560,8 @@ def _zombie_update_tracker_target(
         if _line_of_sight_clear((zombie.x, zombie.y), pos, walls):
             zombie.tracker_target_pos = pos
             zombie.tracker_target_time = fp_time
+            if relock_after is not None and fp_time >= relock_after:
+                zombie.tracker_relock_after_time = None
             return
 
     if (
@@ -1255,9 +1582,45 @@ def _zombie_update_tracker_target(
     next_fp = candidates[0]
     zombie.tracker_target_pos = next_fp.pos
     zombie.tracker_target_time = next_fp.time
+    if relock_after is not None and next_fp.time >= relock_after:
+        zombie.tracker_relock_after_time = None
     return
 
 
+def _zombie_tracker_is_crowded(
+    zombie: Zombie,
+    nearby_zombies: Iterable[Zombie],
+) -> bool:
+    dx = zombie.last_move_dx
+    dy = zombie.last_move_dy
+    if abs(dx) <= 0.001 and abs(dy) <= 0.001:
+        return False
+    angle = math.atan2(dy, dx)
+    angle_step = math.pi / 4.0
+    angle_bin = int(round(angle / angle_step)) % 8
+    dir_x = math.cos(angle_bin * angle_step)
+    dir_y = math.sin(angle_bin * angle_step)
+    perp_x = -dir_y
+    perp_y = dir_x
+    half_width = ZOMBIE_TRACKER_CROWD_BAND_WIDTH * 0.5
+    length = ZOMBIE_TRACKER_CROWD_BAND_LENGTH
+    count = 0
+    for other in nearby_zombies:
+        if other is zombie or not other.alive() or not other.tracker:
+            continue
+        offset_x = other.x - zombie.x
+        offset_y = other.y - zombie.y
+        forward = offset_x * dir_x + offset_y * dir_y
+        if forward <= 0 or forward > length:
+            continue
+        side = offset_x * perp_x + offset_y * perp_y
+        if abs(side) <= half_width:
+            count += 1
+            if count >= ZOMBIE_TRACKER_CROWD_COUNT:
+                return True
+    return False
+
+
 def _zombie_wander_move(
     zombie: Zombie,
     walls: list[Wall],
@@ -1354,7 +1717,7 @@ class Zombie(pygame.sprite.Sprite):
         *,
         speed: float = ZOMBIE_SPEED,
         tracker: bool = False,
-        wall_follower: bool = False,
+        wall_hugging: bool = False,
         movement_strategy: MovementStrategy | None = None,
         aging_duration_frames: float = ZOMBIE_AGING_DURATION_FRAMES,
     ) -> None:
@@ -1362,7 +1725,7 @@ class Zombie(pygame.sprite.Sprite):
         self.radius = ZOMBIE_RADIUS
         self.facing_bin = 0
         self.tracker = tracker
-        self.wall_follower = wall_follower
+        self.wall_hugging = wall_hugging
         self.carbonized = False
         self.directional_images = build_zombie_directional_surfaces(
             self.radius,
@@ -1383,8 +1746,8 @@ class Zombie(pygame.sprite.Sprite):
         if movement_strategy is None:
             if tracker:
                 movement_strategy = _zombie_tracker_movement
-            elif wall_follower:
-                movement_strategy = _zombie_wall_follow_movement
+            elif wall_hugging:
+                movement_strategy = _zombie_wall_hug_movement
             else:
                 movement_strategy = _zombie_normal_movement
         self.movement_strategy = movement_strategy
@@ -1392,11 +1755,12 @@ class Zombie(pygame.sprite.Sprite):
         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
-        self.wall_follow_last_side_has_wall = False
-        self.wall_follow_stuck_flag = False
+        self.tracker_relock_after_time: int | None = None
+        self.wall_hug_side = RNG.choice([-1.0, 1.0]) if wall_hugging else 0.0
+        self.wall_hug_angle = RNG.uniform(0, math.tau) if wall_hugging else None
+        self.wall_hug_last_wall_time: int | None = None
+        self.wall_hug_last_side_has_wall = False
+        self.wall_hug_stuck_flag = False
         self.pos_history: list[tuple[float, float]] = []
         self.wander_angle = RNG.uniform(0, math.tau)
         self.wander_interval_ms = (
@@ -1406,6 +1770,8 @@ class Zombie(pygame.sprite.Sprite):
         self.wander_change_interval = max(
             0, self.wander_interval_ms + RNG.randint(-500, 500)
         )
+        self.last_move_dx = 0.0
+        self.last_move_dy = 0.0
 
     def _update_mode(
         self: Self, player_center: tuple[int, int], sight_range: float
@@ -1478,17 +1844,17 @@ class Zombie(pygame.sprite.Sprite):
         if closest is None:
             return move_x, move_y
 
-        if self.wall_follower:
+        if self.wall_hugging:
             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:
-                    self.wall_follow_angle = self.wander_angle
-                self.wall_follow_angle = (self.wall_follow_angle + math.pi) % math.tau
-                self.wall_follow_side *= -1.0
+                if self.wall_hug_angle is None:
+                    self.wall_hug_angle = self.wander_angle
+                self.wall_hug_angle = (self.wall_hug_angle + math.pi) % math.tau
+                self.wall_hug_side *= -1.0
                 return (
-                    math.cos(self.wall_follow_angle) * self.speed,
-                    math.sin(self.wall_follow_angle) * self.speed,
+                    math.cos(self.wall_hug_angle) * self.speed,
+                    math.sin(self.wall_hug_angle) * self.speed,
                 )
 
         away_dx = next_x - closest.x
@@ -1530,9 +1896,9 @@ class Zombie(pygame.sprite.Sprite):
     def _apply_render_overlays(self: Self) -> None:
         base_surface = self.directional_images[self.facing_bin]
         needs_overlay = self.tracker or (
-            self.wall_follower
-            and self.wall_follow_side != 0
-            and self.wall_follow_last_side_has_wall
+            self.wall_hugging
+            and self.wall_hug_side != 0
+            and self.wall_hug_last_side_has_wall
         )
         if not needs_overlay:
             self.image = base_surface
@@ -1547,11 +1913,11 @@ class Zombie(pygame.sprite.Sprite):
                 color=ZOMBIE_NOSE_COLOR,
             )
         if (
-            self.wall_follower
-            and self.wall_follow_side != 0
-            and self.wall_follow_last_side_has_wall
+            self.wall_hugging
+            and self.wall_hug_side != 0
+            and self.wall_hug_last_side_has_wall
         ):
-            side_sign = 1.0 if self.wall_follow_side > 0 else -1.0
+            side_sign = 1.0 if self.wall_hug_side > 0 else -1.0
             hand_angle = angle_rad + side_sign * (math.pi / 2.0)
             draw_humanoid_hand(
                 self.image,
@@ -1568,17 +1934,50 @@ class Zombie(pygame.sprite.Sprite):
             max_dist_sq = max(
                 (self.x - hx) ** 2 + (self.y - hy) ** 2 for hx, hy in history
             )
-            self.wall_follow_stuck_flag = max_dist_sq < 25
-        if not self.wall_follow_stuck_flag:
+            self.wall_hug_stuck_flag = max_dist_sq < 25
+        if not self.wall_hug_stuck_flag:
             return
-        if self.wall_follower:
-            if self.wall_follow_angle is None:
-                self.wall_follow_angle = self.wander_angle
-            self.wall_follow_angle = (self.wall_follow_angle + math.pi) % math.tau
-            self.wall_follow_side *= -1.0
-        self.wall_follow_stuck_flag = False
+        if self.wall_hugging:
+            if self.wall_hug_angle is None:
+                self.wall_hug_angle = self.wander_angle
+            self.wall_hug_angle = (self.wall_hug_angle + math.pi) % math.tau
+            self.wall_hug_side *= -1.0
+        self.wall_hug_stuck_flag = False
         self.pos_history = []
 
+    def _avoid_pitfalls(
+        self: Self,
+        pitfall_cells: set[tuple[int, int]],
+        cell_size: int,
+    ) -> tuple[float, float]:
+        if cell_size <= 0 or not pitfall_cells:
+            return 0.0, 0.0
+        cell_x = int(self.x // cell_size)
+        cell_y = int(self.y // cell_size)
+        search_cells = 1
+        avoid_radius = cell_size * 1.25
+        max_strength = self.speed * 0.5
+        push_x = 0.0
+        push_y = 0.0
+        for cy in range(cell_y - search_cells, cell_y + search_cells + 1):
+            for cx in range(cell_x - search_cells, cell_x + search_cells + 1):
+                if (cx, cy) not in pitfall_cells:
+                    continue
+                pit_x = (cx + 0.5) * cell_size
+                pit_y = (cy + 0.5) * cell_size
+                dx = self.x - pit_x
+                dy = self.y - pit_y
+                dist_sq = dx * dx + dy * dy
+                if dist_sq <= 0:
+                    continue
+                dist = math.sqrt(dist_sq)
+                if dist >= avoid_radius:
+                    continue
+                strength = (1.0 - dist / avoid_radius) * max_strength
+                push_x += (dx / dist) * strength
+                push_y += (dy / dist) * strength
+        return push_x, push_y
+
     def update(
         self: Self,
         player_center: tuple[int, int],
@@ -1593,6 +1992,7 @@ class Zombie(pygame.sprite.Sprite):
         level_height: int,
         outer_wall_cells: set[tuple[int, int]] | None = None,
         wall_cells: set[tuple[int, int]] | None = None,
+        pitfall_cells: set[tuple[int, int]] | None = None,
         bevel_corners: dict[tuple[int, int], tuple[bool, bool, bool, bool]]
         | None = None,
     ) -> None:
@@ -1609,13 +2009,18 @@ class Zombie(pygame.sprite.Sprite):
             self,
             player_center,
             walls,
+            nearby_zombies,
             footprints or [],
             cell_size,
             grid_cols,
             grid_rows,
             outer_wall_cells,
         )
-        if dist_to_player_sq <= avoid_radius_sq or self.wall_follower:
+        if pitfall_cells is not None:
+            avoid_x, avoid_y = self._avoid_pitfalls(pitfall_cells, cell_size)
+            move_x += avoid_x
+            move_y += avoid_y
+        if dist_to_player_sq <= avoid_radius_sq or self.wall_hugging:
             move_x, move_y = self._avoid_other_zombies(move_x, move_y, nearby_zombies)
         if wall_cells is not None:
             move_x, move_y = apply_tile_edge_nudge(
@@ -1631,6 +2036,8 @@ class Zombie(pygame.sprite.Sprite):
             )
         self._update_facing_from_movement(move_x, move_y)
         self._apply_render_overlays()
+        self.last_move_dx = move_x
+        self.last_move_dy = move_y
         final_x, final_y = self._handle_wall_collision(
             self.x + move_x, self.y + move_y, walls
         )
@@ -1723,6 +2130,8 @@ class Car(pygame.sprite.Sprite):
         walls: Iterable[Wall],
         *,
         walls_nearby: bool = False,
+        cell_size: int | None = None,
+        pitfall_cells: set[tuple[int, int]] | None = None,
     ) -> None:
         if self.health <= 0:
             return
@@ -1746,15 +2155,27 @@ class Car(pygame.sprite.Sprite):
         for wall in possible_walls:
             if _circle_wall_collision(car_center, self.collision_radius, wall):
                 hit_walls.append(wall)
-        if hit_walls:
-            self._take_damage(CAR_WALL_DAMAGE)
-            hit_walls.sort(
-                key=lambda w: (w.rect.centery - self.y) ** 2
-                + (w.rect.centerx - self.x) ** 2
-            )
-            nearest_wall = hit_walls[0]
-            new_x += (self.x - nearest_wall.rect.centerx) * 1.2
-            new_y += (self.y - nearest_wall.rect.centery) * 1.2
+
+        in_pitfall = False
+        if pitfall_cells and cell_size:
+            cx, cy = int(new_x // cell_size), int(new_y // cell_size)
+            if (cx, cy) in pitfall_cells:
+                in_pitfall = True
+
+        if hit_walls or in_pitfall:
+            if hit_walls:
+                self._take_damage(CAR_WALL_DAMAGE)
+                hit_walls.sort(
+                    key=lambda w: (w.rect.centery - self.y) ** 2
+                    + (w.rect.centerx - self.x) ** 2
+                )
+                nearest_wall = hit_walls[0]
+                new_x += (self.x - nearest_wall.rect.centerx) * 1.2
+                new_y += (self.y - nearest_wall.rect.centery) * 1.2
+            else:
+                # Pitfall only: bounce back from current position
+                new_x = self.x - dx * 0.5
+                new_y = self.y - dy * 0.5
 
         self.x = new_x
         self.y = new_y
@@ -1795,6 +2216,7 @@ def _car_body_radius(width: float, height: float) -> float:
 
 __all__ = [
     "Wall",
+    "RubbleWall",
     "SteelBeam",
     "Camera",
     "Player",