zombie-escape 1.5.4__py3-none-any.whl → 1.7.1__py3-none-any.whl

zombie_escape/entities.py

@@ -8,36 +8,19 @@ from typing import Callable, Iterable, Self, Sequence
 import pygame
 from pygame import rect
 
-from .colors import (
-    BLACK,
-    BLUE,
-    DARK_RED,
-    INTERNAL_WALL_BORDER_COLOR,
-    INTERNAL_WALL_COLOR,
-    ORANGE,
-    RED,
-    STEEL_BEAM_COLOR,
-    STEEL_BEAM_LINE_COLOR,
-    TRACKER_OUTLINE_COLOR,
-    WALL_FOLLOWER_OUTLINE_COLOR,
-    YELLOW,
-)
-from .gameplay_constants import (
+from .entities_constants import (
+    BUDDY_FOLLOW_SPEED,
+    BUDDY_RADIUS,
     CAR_HEALTH,
     CAR_HEIGHT,
     CAR_SPEED,
     CAR_WALL_DAMAGE,
     CAR_WIDTH,
-    BUDDY_COLOR,
-    BUDDY_FOLLOW_SPEED,
-    BUDDY_RADIUS,
     FAST_ZOMBIE_BASE_SPEED,
     FLASHLIGHT_HEIGHT,
     FLASHLIGHT_WIDTH,
     FUEL_CAN_HEIGHT,
     FUEL_CAN_WIDTH,
-    HUMANOID_OUTLINE_COLOR,
-    HUMANOID_OUTLINE_WIDTH,
     INTERNAL_WALL_BEVEL_DEPTH,
     INTERNAL_WALL_HEALTH,
     PLAYER_RADIUS,
@@ -46,7 +29,6 @@ from .gameplay_constants import (
     STEEL_BEAM_HEALTH,
     SURVIVOR_APPROACH_RADIUS,
     SURVIVOR_APPROACH_SPEED,
-    SURVIVOR_COLOR,
     SURVIVOR_RADIUS,
     ZOMBIE_AGING_DURATION_FRAMES,
     ZOMBIE_AGING_MIN_SPEED_RATIO,
@@ -64,28 +46,52 @@ from .gameplay_constants import (
     ZOMBIE_WALL_FOLLOW_SENSOR_DISTANCE,
     ZOMBIE_WALL_FOLLOW_TARGET_GAP,
     ZOMBIE_WANDER_INTERVAL_MS,
-    car_body_radius,
 )
-from .level_constants import CELL_SIZE, GRID_COLS, GRID_ROWS, LEVEL_HEIGHT, LEVEL_WIDTH
-from .screen_constants import SCREEN_HEIGHT, SCREEN_WIDTH
+from .render_assets import (
+    EnvironmentPalette,
+    build_beveled_polygon,
+    build_car_surface,
+    build_flashlight_surface,
+    build_fuel_can_surface,
+    build_player_surface,
+    build_survivor_surface,
+    build_zombie_surface,
+    paint_car_surface,
+    paint_steel_beam_surface,
+    paint_wall_surface,
+    paint_zombie_surface,
+    resolve_car_color,
+    resolve_steel_beam_colors,
+    resolve_wall_colors,
+)
 from .rng import get_rng
+from .screen_constants import SCREEN_HEIGHT, SCREEN_WIDTH
 
 RNG = get_rng()
 
 MovementStrategy = Callable[
-    ["Zombie", tuple[int, int], list["Wall"], list[dict[str, object]]],
+    [
+        "Zombie",
+        tuple[int, int],
+        list["Wall"],
+        list[dict[str, object]],
+        int,
+        int,
+        int,
+        set[tuple[int, int]] | None,
+    ],
     tuple[float, float],
 ]
 WallIndex = dict[tuple[int, int], list["Wall"]]
 
 
-def build_wall_index(walls: Iterable["Wall"]) -> WallIndex:
+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)
+        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
 
@@ -101,13 +107,23 @@ def _sprite_center_and_radius(
 
 
 def walls_for_radius(
-    wall_index: WallIndex, center: tuple[float, float], radius: float
+    wall_index: WallIndex,
+    center: tuple[float, float],
+    radius: float,
+    *,
+    cell_size: int,
+    grid_cols: int | None = None,
+    grid_rows: int | None = None,
 ) -> list["Wall"]:
-    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))
+    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):
@@ -116,13 +132,33 @@ def walls_for_radius(
 
 
 def _walls_for_sprite(
-    sprite: pygame.sprite.Sprite, wall_index: WallIndex
+    sprite: pygame.sprite.Sprite,
+    wall_index: WallIndex,
+    *,
+    cell_size: int,
+    grid_cols: int | None = None,
+    grid_rows: int | None = None,
 ) -> list["Wall"]:
     center, radius = _sprite_center_and_radius(sprite)
-    return walls_for_radius(wall_index, center, radius)
+    return walls_for_radius(
+        wall_index,
+        center,
+        radius,
+        cell_size=cell_size,
+        grid_cols=grid_cols,
+        grid_rows=grid_rows,
+    )
 
 
-def circle_rect_collision(
+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:
     """Return True if a circle overlaps the provided rectangle."""
@@ -134,80 +170,13 @@ def circle_rect_collision(
     return dx * dx + dy * dy <= radius * radius
 
 
-def _draw_outlined_circle(
-    surface: pygame.Surface,
-    center: tuple[int, int],
-    radius: int,
-    fill_color: tuple[int, int, int],
-    outline_color: tuple[int, int, int],
-    outline_width: int,
-) -> None:
-    pygame.draw.circle(surface, fill_color, center, radius)
-    if outline_width > 0:
-        pygame.draw.circle(surface, outline_color, center, radius, width=outline_width)
-
-
 def _build_beveled_polygon(
     width: int,
     height: int,
     depth: int,
     bevels: tuple[bool, bool, bool, bool],
 ) -> list[tuple[int, int]]:
-    d = max(0, min(depth, width // 2, height // 2))
-    if d == 0 or not any(bevels):
-        return [(0, 0), (width, 0), (width, height), (0, height)]
-
-    segments = 4
-    tl, tr, br, bl = bevels
-    points: list[tuple[int, int]] = []
-
-    def add_point(x: float, y: float) -> None:
-        point = (int(round(x)), int(round(y)))
-        if not points or points[-1] != point:
-            points.append(point)
-
-    def add_arc(
-        center_x: float,
-        center_y: float,
-        radius: float,
-        start_deg: float,
-        end_deg: float,
-        *,
-        skip_first: bool = False,
-        skip_last: bool = False,
-    ) -> None:
-        for i in range(segments + 1):
-            if skip_first and i == 0:
-                continue
-            if skip_last and i == segments:
-                continue
-            t = i / segments
-            angle = math.radians(start_deg + (end_deg - start_deg) * t)
-            add_point(
-                center_x + radius * math.cos(angle),
-                center_y + radius * math.sin(angle),
-            )
-
-    add_point(d if tl else 0, 0)
-    if tr:
-        add_point(width - d, 0)
-        add_arc(width - d, d, d, -90, 0, skip_first=True)
-    else:
-        add_point(width, 0)
-    if br:
-        add_point(width, height - d)
-        add_arc(width - d, height - d, d, 0, 90, skip_first=True)
-    else:
-        add_point(width, height)
-    if bl:
-        add_point(d, height)
-        add_arc(d, height - d, d, 90, 180, skip_first=True)
-    else:
-        add_point(0, height)
-    if tl:
-        add_point(0, d)
-        add_arc(d, d, d, 180, 270, skip_first=True, skip_last=True)
-    return points
+    return build_beveled_polygon(width, height, depth, bevels)
 
 
 def _point_in_polygon(
@@ -345,9 +314,9 @@ def collide_sprite_wall(
     if hasattr(sprite, "radius"):
         center = sprite.rect.center
         radius = float(getattr(sprite, "radius"))
-        if hasattr(wall, "collides_circle"):
-            return wall.collides_circle(center, radius)
-        return circle_rect_collision(center, radius, wall.rect)
+        if hasattr(wall, "_collides_circle"):
+            return wall._collides_circle(center, radius)
+        return _circle_rect_collision(center, radius, wall.rect)
     if hasattr(wall, "collides_rect"):
         return wall.collides_rect(sprite.rect)
     if hasattr(sprite, "collides_rect"):
@@ -355,18 +324,29 @@ def collide_sprite_wall(
     return sprite.rect.colliderect(wall.rect)
 
 
-def spritecollide_walls(
+def _spritecollide_walls(
     sprite: pygame.sprite.Sprite,
     walls: pygame.sprite.Group,
     *,
     dokill: bool = False,
     wall_index: WallIndex | None = None,
+    cell_size: int | None = None,
+    grid_cols: int | None = None,
+    grid_rows: int | None = None,
 ) -> list[pygame.sprite.Sprite]:
     if wall_index is None:
         return pygame.sprite.spritecollide(
             sprite, walls, dokill, collided=collide_sprite_wall
         )
-    candidates = _walls_for_sprite(sprite, wall_index)
+    if cell_size is None:
+        raise ValueError("cell_size is required when using wall_index")
+    candidates = _walls_for_sprite(
+        sprite,
+        wall_index,
+        cell_size=cell_size,
+        grid_cols=grid_cols,
+        grid_rows=grid_rows,
+    )
     if not candidates:
         return []
     hit_list = [wall for wall in candidates if collide_sprite_wall(sprite, wall)]
@@ -381,28 +361,38 @@ def spritecollideany_walls(
     walls: pygame.sprite.Group,
     *,
     wall_index: WallIndex | None = None,
+    cell_size: int | None = None,
+    grid_cols: int | None = None,
+    grid_rows: int | None = None,
 ) -> pygame.sprite.Sprite | None:
     if wall_index is None:
         return pygame.sprite.spritecollideany(
             sprite, walls, collided=collide_sprite_wall
         )
-    for wall in _walls_for_sprite(sprite, wall_index):
+    if cell_size is None:
+        raise ValueError("cell_size is required when using wall_index")
+    for wall in _walls_for_sprite(
+        sprite,
+        wall_index,
+        cell_size=cell_size,
+        grid_cols=grid_cols,
+        grid_rows=grid_rows,
+    ):
         if collide_sprite_wall(sprite, wall):
             return wall
     return None
 
 
-def circle_wall_collision(
+def _circle_wall_collision(
     center: tuple[float, float],
     radius: float,
     wall: pygame.sprite.Sprite,
 ) -> bool:
-    if hasattr(wall, "collides_circle"):
-        return wall.collides_circle(center, radius)
-    return circle_rect_collision(center, radius, wall.rect)
+    if hasattr(wall, "_collides_circle"):
+        return wall._collides_circle(center, radius)
+    return _circle_rect_collision(center, radius, wall.rect)
 
 
-# --- Camera Class ---
 class Wall(pygame.sprite.Sprite):
     def __init__(
         self: Self,
@@ -412,8 +402,7 @@ class Wall(pygame.sprite.Sprite):
         height: int,
         *,
         health: int = INTERNAL_WALL_HEALTH,
-        color: tuple[int, int, int] = INTERNAL_WALL_COLOR,
-        border_color: tuple[int, int, int] = INTERNAL_WALL_BORDER_COLOR,
+        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,
@@ -426,8 +415,7 @@ class Wall(pygame.sprite.Sprite):
         safe_width = max(1, width)
         safe_height = max(1, height)
         self.image = pygame.Surface((safe_width, safe_height), pygame.SRCALPHA)
-        self.base_color = color
-        self.border_base_color = border_color
+        self.palette = palette
         self.palette_category = palette_category
         self.health = health
         self.max_health = max(1, health)
@@ -440,18 +428,15 @@ class Wall(pygame.sprite.Sprite):
         self._local_polygon = _build_beveled_polygon(
             safe_width, safe_height, self.bevel_depth, self.bevel_mask
         )
-        self.update_color()
+        self._update_color()
         self.rect = self.image.get_rect(topleft=(x, y))
-        self._collision_polygon = (
-            [(px + self.rect.x, py + self.rect.y) for px, py in self._local_polygon]
-            if self.bevel_depth > 0 and any(self.bevel_mask)
-            else None
-        )
+        # Keep collision rectangular even when beveled visually.
+        self._collision_polygon = None
 
-    def take_damage(self: Self, *, amount: int = 1) -> None:
+    def _take_damage(self: Self, *, amount: int = 1) -> None:
         if self.health > 0:
             self.health -= amount
-            self.update_color()
+            self._update_color()
             if self.health <= 0:
                 if self.on_destroy:
                     try:
@@ -460,135 +445,61 @@ class Wall(pygame.sprite.Sprite):
                         print(f"Wall destroy callback failed: {exc}")
                 self.kill()
 
-    def update_color(self: Self) -> None:
-        self.image.fill((0, 0, 0, 0))
+    def _update_color(self: Self) -> None:
         if self.health <= 0:
-            health_ratio = 0
-            fill_color = (40, 40, 40)
-        else:
-            health_ratio = max(0, self.health / self.max_health)
-            mix = (
-                0.6 + 0.4 * health_ratio
-            )  # keep at least 60% of the base color even when nearly destroyed
-            r = int(self.base_color[0] * mix)
-            g = int(self.base_color[1] * mix)
-            b = int(self.base_color[2] * mix)
-            fill_color = (r, g, b)
-        # Bright edge to separate walls from floor
-        br = int(self.border_base_color[0] * (0.6 + 0.4 * health_ratio))
-        bg = int(self.border_base_color[1] * (0.6 + 0.4 * health_ratio))
-        bb = int(self.border_base_color[2] * (0.6 + 0.4 * health_ratio))
-        border_color = (br, bg, bb)
-
-        rect_obj = self.image.get_rect()
-        side_height = 0
-        if self.draw_bottom_side:
-            side_height = max(1, int(rect_obj.height * self.bottom_side_ratio))
-
-        def draw_face(
-            target: pygame.Surface,
-            *,
-            face_size: tuple[int, int] | None = None,
-        ) -> None:
-            face_width, face_height = face_size or target.get_size()
-            if self.bevel_depth > 0 and any(self.bevel_mask):
-                face_polygon = _build_beveled_polygon(
-                    face_width, face_height, self.bevel_depth, self.bevel_mask
-                )
-                pygame.draw.polygon(target, border_color, face_polygon)
-            else:
-                target.fill(border_color)
-            border_width = 18
-            inner_rect = target.get_rect().inflate(-border_width, -border_width)
-            if inner_rect.width > 0 and inner_rect.height > 0:
-                inner_depth = max(0, self.bevel_depth - border_width)
-                if inner_depth > 0 and any(self.bevel_mask):
-                    inner_polygon = _build_beveled_polygon(
-                        inner_rect.width,
-                        inner_rect.height,
-                        inner_depth,
-                        self.bevel_mask,
-                    )
-                    inner_points = [
-                        (px + inner_rect.x, py + inner_rect.y)
-                        for px, py in inner_polygon
-                    ]
-                    pygame.draw.polygon(target, fill_color, inner_points)
-                else:
-                    pygame.draw.rect(target, fill_color, inner_rect)
-
-        if self.draw_bottom_side:
-            extra_height = max(0, int(self.bevel_depth / 2))
-            side_draw_height = min(rect_obj.height, side_height + extra_height)
-            side_rect = pygame.Rect(
-                rect_obj.left,
-                rect_obj.bottom - side_draw_height,
-                rect_obj.width,
-                side_draw_height,
-            )
-            side_color = tuple(int(c * self.side_shade_ratio) for c in fill_color)
-            side_surface = pygame.Surface(rect_obj.size, pygame.SRCALPHA)
-            if self.bevel_depth > 0 and any(self.bevel_mask):
-                pygame.draw.polygon(side_surface, side_color, self._local_polygon)
-            else:
-                pygame.draw.rect(side_surface, side_color, rect_obj)
-            self.image.blit(side_surface, side_rect.topleft, area=side_rect)
-
-        if self.draw_bottom_side:
-            top_height = max(0, rect_obj.height - side_height)
-            top_rect = pygame.Rect(
-                rect_obj.left,
-                rect_obj.top,
-                rect_obj.width,
-                rect_obj.height - side_height,
-            )
-            top_surface = pygame.Surface((rect_obj.width, top_height), pygame.SRCALPHA)
-            draw_face(
-                top_surface,
-                face_size=(rect_obj.width, top_height),
-            )
-            if top_rect.height > 0:
-                self.image.blit(top_surface, top_rect.topleft, area=top_rect)
+            health_ratio = 0.0
         else:
-            draw_face(self.image)
+            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):
+    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_colors(
-        self: Self,
-        *,
-        color: tuple[int, int, int],
-        border_color: tuple[int, int, int],
-        force: bool = False,
+    def set_palette(
+        self: Self, palette: EnvironmentPalette | None, *, force: bool = False
     ) -> None:
-        """Update the wall's base colors to match the current ambient palette."""
+        """Update the wall's palette to match the current ambient palette."""
 
-        if (
-            not force
-            and self.base_color == color
-            and self.border_base_color == border_color
-        ):
+        if not force and self.palette is palette:
             return
-        self.base_color = color
-        self.border_base_color = border_color
-        self.update_color()
+        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
+        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.
@@ -597,56 +508,31 @@ class SteelBeam(pygame.sprite.Sprite):
         self.image = pygame.Surface((inset_size, inset_size), pygame.SRCALPHA)
         self.health = health
         self.max_health = max(1, health)
-        self.base_color = STEEL_BEAM_COLOR
-        self.line_color = STEEL_BEAM_LINE_COLOR
-        self.update_color()
+        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:
+    def _take_damage(self: Self, *, amount: int = 1) -> None:
         if self.health > 0:
             self.health -= amount
-            self.update_color()
+            self._update_color()
             if self.health <= 0:
                 self.kill()
 
-    def update_color(self: Self) -> None:
+    def _update_color(self: Self) -> None:
         """Render a simple square with crossed diagonals that darkens as damaged."""
-        self.image.fill((0, 0, 0, 0))
         if self.health <= 0:
             return
         health_ratio = max(0, self.health / self.max_health)
-        fill_mix = 0.55 + 0.45 * health_ratio
-        fill_color = tuple(int(c * fill_mix) for c in self.base_color)
-        rect_obj = self.image.get_rect()
-        side_height = max(1, int(rect_obj.height * 0.1))
-        top_rect = pygame.Rect(
-            rect_obj.left,
-            rect_obj.top,
-            rect_obj.width,
-            rect_obj.height - side_height,
-        )
-        side_mix = 0.45 + 0.35 * health_ratio
-        side_color = tuple(int(c * side_mix * 0.9) for c in self.base_color)
-        side_rect = pygame.Rect(
-            rect_obj.left,
-            rect_obj.bottom - side_height,
-            rect_obj.width,
-            side_height,
+        base_color, line_color = resolve_steel_beam_colors(
+            health_ratio=health_ratio, palette=self.palette
         )
-        pygame.draw.rect(self.image, side_color, side_rect)
-        line_mix = 0.7 + 0.3 * health_ratio
-        line_color = tuple(int(c * line_mix) for c in self.line_color)
-        top_surface = pygame.Surface(top_rect.size, pygame.SRCALPHA)
-        local_rect = top_surface.get_rect()
-        pygame.draw.rect(top_surface, fill_color, local_rect)
-        pygame.draw.rect(top_surface, line_color, local_rect, width=6)
-        pygame.draw.line(
-            top_surface, line_color, local_rect.topleft, local_rect.bottomright, width=6
-        )
-        pygame.draw.line(
-            top_surface, line_color, local_rect.topright, local_rect.bottomleft, width=6
+        paint_steel_beam_surface(
+            self.image,
+            base_color=base_color,
+            line_color=line_color,
+            health_ratio=health_ratio,
         )
-        self.image.blit(top_surface, top_rect.topleft)
 
 
 class Camera:
@@ -671,20 +557,14 @@ class Camera:
 
 # --- Game Classes ---
 class Player(pygame.sprite.Sprite):
-    def __init__(self: Self, x: float, y: float) -> None:
+    def __init__(
+        self: Self,
+        x: float,
+        y: float,
+    ) -> None:
         super().__init__()
         self.radius = PLAYER_RADIUS
-        self.image = pygame.Surface(
-            (self.radius * 2 + 2, self.radius * 2 + 2), pygame.SRCALPHA
-        )
-        _draw_outlined_circle(
-            self.image,
-            (self.radius + 1, self.radius + 1),
-            self.radius,
-            BLUE,
-            HUMANOID_OUTLINE_COLOR,
-            HUMANOID_OUTLINE_WIDTH,
-        )
+        self.image = build_player_surface(self.radius)
         self.rect = self.image.get_rect(center=(x, y))
         self.speed = PLAYER_SPEED
         self.in_car = False
@@ -698,33 +578,49 @@ class Player(pygame.sprite.Sprite):
         walls: pygame.sprite.Group,
         *,
         wall_index: WallIndex | None = None,
+        cell_size: int | None = None,
+        level_width: int | None = None,
+        level_height: int | None = None,
     ) -> None:
         if self.in_car:
             return
 
+        if level_width is None or level_height is None:
+            raise ValueError("level_width/level_height are required for movement")
+
         if dx != 0:
             self.x += dx
-            self.x = min(LEVEL_WIDTH, max(0, self.x))
+            self.x = min(level_width, max(0, self.x))
             self.rect.centerx = int(self.x)
-            hit_list_x = spritecollide_walls(self, walls, wall_index=wall_index)
+            hit_list_x = _spritecollide_walls(
+                self,
+                walls,
+                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)
+                        wall._take_damage(amount=damage)
                 self.x -= dx * 1.5
                 self.rect.centerx = int(self.x)
 
         if dy != 0:
             self.y += dy
-            self.y = min(LEVEL_HEIGHT, max(0, self.y))
+            self.y = min(level_height, max(0, self.y))
             self.rect.centery = int(self.y)
-            hit_list_y = spritecollide_walls(self, walls, wall_index=wall_index)
+            hit_list_y = _spritecollide_walls(
+                self,
+                walls,
+                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)
+                        wall._take_damage(amount=damage)
                 self.y -= dy * 1.5
                 self.rect.centery = int(self.y)
 
@@ -734,19 +630,19 @@ class Player(pygame.sprite.Sprite):
 class Survivor(pygame.sprite.Sprite):
     """Civilians that gather near the player; optional buddy behavior."""
 
-    def __init__(self: Self, x: float, y: float, *, is_buddy: bool = False) -> None:
+    def __init__(
+        self: Self,
+        x: float,
+        y: float,
+        *,
+        is_buddy: bool = False,
+    ) -> None:
         super().__init__()
         self.is_buddy = is_buddy
         self.radius = BUDDY_RADIUS if is_buddy else SURVIVOR_RADIUS
-        self.image = pygame.Surface((self.radius * 2, self.radius * 2), pygame.SRCALPHA)
-        fill_color = BUDDY_COLOR if is_buddy else SURVIVOR_COLOR
-        _draw_outlined_circle(
-            self.image,
-            (self.radius, self.radius),
+        self.image = build_survivor_surface(
             self.radius,
-            fill_color,
-            HUMANOID_OUTLINE_COLOR,
-            HUMANOID_OUTLINE_WIDTH,
+            is_buddy=is_buddy,
         )
         self.rect = self.image.get_rect(center=(int(x), int(y)))
         self.x = float(self.rect.centerx)
@@ -776,7 +672,12 @@ class Survivor(pygame.sprite.Sprite):
         walls: pygame.sprite.Group,
         *,
         wall_index: WallIndex | None = None,
+        cell_size: int | None = None,
+        level_width: int | None = None,
+        level_height: int | None = None,
     ) -> None:
+        if level_width is None or level_height is None:
+            raise ValueError("level_width/level_height are required for movement")
         if self.is_buddy:
             if self.rescued or not self.following:
                 self.rect.center = (int(self.x), int(self.y))
@@ -784,96 +685,155 @@ class Survivor(pygame.sprite.Sprite):
 
             dx = player_pos[0] - self.x
             dy = player_pos[1] - self.y
-            dist = math.hypot(dx, dy)
-            if dist <= 0:
+            dist_sq = dx * dx + dy * dy
+            if dist_sq <= 0:
                 self.rect.center = (int(self.x), int(self.y))
                 return
 
+            dist = math.sqrt(dist_sq)
             move_x = (dx / dist) * BUDDY_FOLLOW_SPEED
             move_y = (dy / dist) * BUDDY_FOLLOW_SPEED
 
             if move_x:
                 self.x += move_x
                 self.rect.centerx = int(self.x)
-                if spritecollideany_walls(self, walls, wall_index=wall_index):
+                if spritecollideany_walls(
+                    self,
+                    walls,
+                    wall_index=wall_index,
+                    cell_size=cell_size,
+                ):
                     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(self, walls, wall_index=wall_index):
+                if spritecollideany_walls(
+                    self,
+                    walls,
+                    wall_index=wall_index,
+                    cell_size=cell_size,
+                ):
                     self.y -= move_y
                     self.rect.centery = int(self.y)
 
             overlap_radius = (self.radius + PLAYER_RADIUS) * 1.05
             dx_after = player_pos[0] - self.x
             dy_after = player_pos[1] - self.y
-            dist_after = math.hypot(dx_after, dy_after)
-            if dist_after > 0 and dist_after < overlap_radius:
+            dist_after_sq = dx_after * dx_after + dy_after * dy_after
+            if 0 < dist_after_sq < overlap_radius * overlap_radius:
+                dist_after = math.sqrt(dist_after_sq)
                 push_dist = overlap_radius - dist_after
                 self.x -= (dx_after / dist_after) * push_dist
                 self.y -= (dy_after / dist_after) * push_dist
                 self.rect.center = (int(self.x), int(self.y))
 
-            self.x = min(LEVEL_WIDTH, max(0, self.x))
-            self.y = min(LEVEL_HEIGHT, max(0, self.y))
+            self.x = min(level_width, max(0, self.x))
+            self.y = min(level_height, max(0, self.y))
             self.rect.center = (int(self.x), int(self.y))
             return
 
         dx = player_pos[0] - self.x
         dy = player_pos[1] - self.y
-        dist = math.hypot(dx, dy)
-        if dist <= 0 or dist > SURVIVOR_APPROACH_RADIUS:
+        dist_sq = dx * dx + dy * dy
+        if (
+            dist_sq <= 0
+            or dist_sq > SURVIVOR_APPROACH_RADIUS * SURVIVOR_APPROACH_RADIUS
+        ):
             return
 
+        dist = math.sqrt(dist_sq)
         move_x = (dx / dist) * SURVIVOR_APPROACH_SPEED
         move_y = (dy / dist) * SURVIVOR_APPROACH_SPEED
 
         if move_x:
             self.x += move_x
             self.rect.centerx = int(self.x)
-            if spritecollideany_walls(self, walls, wall_index=wall_index):
+            if spritecollideany_walls(
+                self,
+                walls,
+                wall_index=wall_index,
+                cell_size=cell_size,
+            ):
                 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(self, walls, wall_index=wall_index):
+            if spritecollideany_walls(
+                self,
+                walls,
+                wall_index=wall_index,
+                cell_size=cell_size,
+            ):
                 self.y -= move_y
                 self.rect.centery = int(self.y)
 
         self.rect.center = (int(self.x), int(self.y))
 
 
-def random_position_outside_building() -> tuple[int, int]:
+def random_position_outside_building(
+    level_width: int, level_height: int
+) -> tuple[int, int]:
     side = RNG.choice(["top", "bottom", "left", "right"])
     margin = 0
     if side == "top":
-        x, y = RNG.randint(0, LEVEL_WIDTH), -margin
+        x, y = RNG.randint(0, level_width), -margin
     elif side == "bottom":
-        x, y = RNG.randint(0, LEVEL_WIDTH), LEVEL_HEIGHT + margin
+        x, y = RNG.randint(0, level_width), level_height + margin
     elif side == "left":
-        x, y = -margin, RNG.randint(0, LEVEL_HEIGHT)
+        x, y = -margin, RNG.randint(0, level_height)
     else:
-        x, y = LEVEL_WIDTH + margin, RNG.randint(0, LEVEL_HEIGHT)
+        x, y = level_width + margin, RNG.randint(0, level_height)
     return x, y
 
 
-def zombie_tracker_movement(
+def _zombie_tracker_movement(
     zombie: Zombie,
     player_center: tuple[int, int],
     walls: list[Wall],
     footprints: list[dict[str, object]],
+    cell_size: int,
+    grid_cols: int,
+    grid_rows: int,
+    outer_wall_cells: set[tuple[int, int]] | None,
 ) -> 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)
         if zombie.tracker_target_pos is not None:
             return zombie_move_toward(zombie, zombie.tracker_target_pos)
-        return zombie_wander_move(zombie, walls)
+        return _zombie_wander_move(
+            zombie,
+            walls,
+            cell_size=cell_size,
+            grid_cols=grid_cols,
+            grid_rows=grid_rows,
+            outer_wall_cells=outer_wall_cells,
+        )
     return zombie_move_toward(zombie, player_center)
 
 
+def zombie_wander_movement(
+    zombie: Zombie,
+    _player_center: tuple[int, int],
+    walls: list[Wall],
+    _footprints: list[dict[str, object]],
+    cell_size: int,
+    grid_cols: int,
+    grid_rows: int,
+    outer_wall_cells: set[tuple[int, int]] | None,
+) -> tuple[float, float]:
+    return _zombie_wander_move(
+        zombie,
+        walls,
+        cell_size=cell_size,
+        grid_cols=grid_cols,
+        grid_rows=grid_rows,
+        outer_wall_cells=outer_wall_cells,
+    )
+
+
 def zombie_wall_follow_has_wall(
     zombie: Zombie,
     walls: list[Wall],
@@ -889,12 +849,12 @@ def zombie_wall_follow_has_wall(
         and abs(wall.rect.centery - check_y) < 120
     ]
     return any(
-        circle_wall_collision((check_x, check_y), zombie.radius, wall)
+        _circle_wall_collision((check_x, check_y), zombie.radius, wall)
         for wall in candidates
     )
 
 
-def zombie_wall_follow_wall_distance(
+def _zombie_wall_follow_wall_distance(
     zombie: Zombie,
     walls: list[Wall],
     angle: float,
@@ -918,7 +878,7 @@ def zombie_wall_follow_wall_distance(
         check_x = zombie.x + direction_x * distance
         check_y = zombie.y + direction_y * distance
         if any(
-            circle_wall_collision((check_x, check_y), zombie.radius, wall)
+            _circle_wall_collision((check_x, check_y), zombie.radius, wall)
             for wall in candidates
         ):
             return distance
@@ -926,11 +886,15 @@ def zombie_wall_follow_wall_distance(
     return max_distance
 
 
-def zombie_wall_follow_movement(
+def _zombie_wall_follow_movement(
     zombie: Zombie,
     player_center: tuple[int, int],
     walls: list[Wall],
     _footprints: list[dict[str, object]],
+    cell_size: int,
+    grid_cols: int,
+    grid_rows: int,
+    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:
@@ -941,13 +905,13 @@ def zombie_wall_follow_movement(
         probe_offset = math.radians(ZOMBIE_WALL_FOLLOW_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_follow_wall_distance(
             zombie, walls, left_angle, sensor_distance
         )
-        right_dist = zombie_wall_follow_wall_distance(
+        right_dist = _zombie_wall_follow_wall_distance(
             zombie, walls, right_angle, sensor_distance
         )
-        forward_dist = zombie_wall_follow_wall_distance(
+        forward_dist = _zombie_wall_follow_wall_distance(
             zombie, walls, forward_angle, sensor_distance
         )
         left_wall = left_dist < sensor_distance
@@ -967,15 +931,22 @@ def zombie_wall_follow_movement(
         else:
             if is_in_sight:
                 return zombie_move_toward(zombie, player_center)
-            return zombie_wander_move(zombie, walls)
+            return _zombie_wander_move(
+                zombie,
+                walls,
+                cell_size=cell_size,
+                grid_cols=grid_cols,
+                grid_rows=grid_rows,
+                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(
+    side_dist = _zombie_wall_follow_wall_distance(
         zombie, walls, side_angle, sensor_distance
     )
-    forward_dist = zombie_wall_follow_wall_distance(
+    forward_dist = _zombie_wall_follow_wall_distance(
         zombie, walls, zombie.wall_follow_angle, sensor_distance
     )
     side_has_wall = side_dist < sensor_distance
@@ -1024,14 +995,25 @@ def zombie_normal_movement(
     player_center: tuple[int, int],
     walls: list[Wall],
     _footprints: list[dict[str, object]],
+    cell_size: int,
+    grid_cols: int,
+    grid_rows: int,
+    outer_wall_cells: set[tuple[int, int]] | None,
 ) -> tuple[float, float]:
     is_in_sight = zombie._update_mode(player_center, ZOMBIE_SIGHT_RANGE)
     if not is_in_sight:
-        return zombie_wander_move(zombie, walls)
+        return _zombie_wander_move(
+            zombie,
+            walls,
+            cell_size=cell_size,
+            grid_cols=grid_cols,
+            grid_rows=grid_rows,
+            outer_wall_cells=outer_wall_cells,
+        )
     return zombie_move_toward(zombie, player_center)
 
 
-def zombie_update_tracker_target(
+def _zombie_update_tracker_target(
     zombie: Zombie, footprints: list[dict[str, object]]
 ) -> None:
     zombie.tracker_target_pos = None
@@ -1044,7 +1026,10 @@ def zombie_update_tracker_target(
             continue
         dx = pos[0] - zombie.x
         dy = pos[1] - zombie.y
-        if math.hypot(dx, dy) <= ZOMBIE_TRACKER_SCENT_RADIUS:
+        if (
+            dx * dx + dy * dy
+            <= ZOMBIE_TRACKER_SCENT_RADIUS * ZOMBIE_TRACKER_SCENT_RADIUS
+        ):
             nearby.append(fp)
 
     if not nearby:
@@ -1052,16 +1037,22 @@ def zombie_update_tracker_target(
 
     latest = max(
         nearby,
-        key=lambda fp: fp.get("time", -1)
-        if isinstance(fp.get("time"), int)
-        else -1,
+        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
 
 
-def zombie_wander_move(zombie: Zombie, walls: list[Wall]) -> tuple[float, float]:
+def _zombie_wander_move(
+    zombie: Zombie,
+    walls: list[Wall],
+    *,
+    cell_size: int,
+    grid_cols: int,
+    grid_rows: int,
+    outer_wall_cells: set[tuple[int, int]] | None,
+) -> tuple[float, float]:
     now = pygame.time.get_ticks()
     if now - zombie.last_wander_change_time > zombie.wander_change_interval:
         zombie.wander_angle = RNG.uniform(0, math.tau)
@@ -1069,24 +1060,29 @@ def zombie_wander_move(zombie: Zombie, walls: list[Wall]) -> tuple[float, float]
         jitter = RNG.randint(-500, 500)
         zombie.wander_change_interval = max(0, zombie.wander_interval_ms + jitter)
 
-    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)
+    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 at_x_edge or at_y_edge:
-        if zombie.outer_wall_cells is not None:
+        if outer_wall_cells is not None:
             if at_x_edge:
-                inward_cell = (1, cell_y) if cell_x == 0 else (GRID_COLS - 2, cell_y)
-                if inward_cell not in zombie.outer_wall_cells:
+                inward_cell = (
+                    (1, cell_y) if cell_x == 0 else (grid_cols - 2, cell_y)
+                )
+                if inward_cell not in outer_wall_cells:
                     inward_dx = zombie.speed if cell_x == 0 else -zombie.speed
                     return inward_dx, 0.0
             if at_y_edge:
-                inward_cell = (cell_x, 1) if cell_y == 0 else (cell_x, GRID_ROWS - 2)
-                if inward_cell not in zombie.outer_wall_cells:
+                inward_cell = (
+                    (cell_x, 1) if cell_y == 0 else (cell_x, grid_rows - 2)
+                )
+                if inward_cell not in outer_wall_cells:
                     inward_dy = zombie.speed if cell_y == 0 else -zombie.speed
                     return 0.0, inward_dy
         else:
+
             def path_clear(next_x: float, next_y: float) -> bool:
                 nearby_walls = [
                     wall
@@ -1095,7 +1091,7 @@ def zombie_wander_move(zombie: Zombie, walls: list[Wall]) -> tuple[float, float]
                     and abs(wall.rect.centery - next_y) < 120
                 ]
                 return not any(
-                    circle_wall_collision((next_x, next_y), zombie.radius, wall)
+                    _circle_wall_collision((next_x, next_y), zombie.radius, wall)
                     for wall in nearby_walls
                 )
 
@@ -1133,43 +1129,24 @@ def zombie_move_toward(
 class Zombie(pygame.sprite.Sprite):
     def __init__(
         self: Self,
+        x: float,
+        y: float,
         *,
-        start_pos: tuple[int, int] | None = None,
-        hint_pos: tuple[float, float] | None = None,
         speed: float = ZOMBIE_SPEED,
         tracker: bool = False,
         wall_follower: bool = False,
         movement_strategy: MovementStrategy | None = None,
         aging_duration_frames: float = ZOMBIE_AGING_DURATION_FRAMES,
-        outer_wall_cells: set[tuple[int, int]] | None = None,
     ) -> None:
         super().__init__()
         self.radius = ZOMBIE_RADIUS
-        self.image = pygame.Surface((self.radius * 2, self.radius * 2), pygame.SRCALPHA)
-        if tracker:
-            outline_color = TRACKER_OUTLINE_COLOR
-        elif wall_follower:
-            outline_color = WALL_FOLLOWER_OUTLINE_COLOR
-        else:
-            outline_color = DARK_RED
-        _draw_outlined_circle(
-            self.image,
-            (self.radius, self.radius),
-            self.radius,
-            RED,
-            outline_color,
-            1,
+        self.tracker = tracker
+        self.wall_follower = wall_follower
+        self.carbonized = False
+        self.image = build_zombie_surface(
+            self.radius, tracker=self.tracker, wall_follower=self.wall_follower
         )
-        if start_pos:
-            x, y = start_pos
-        elif hint_pos:
-            points = [random_position_outside_building() for _ in range(5)]
-            points.sort(
-                key=lambda p: math.hypot(p[0] - hint_pos[0], p[1] - hint_pos[1])
-            )
-            x, y = points[0]
-        else:
-            x, y = random_position_outside_building()
+        self._redraw_image()
         self.rect = self.image.get_rect(center=(x, y))
         jitter_base = FAST_ZOMBIE_BASE_SPEED if speed > ZOMBIE_SPEED else ZOMBIE_SPEED
         jitter = jitter_base * 0.2
@@ -1179,27 +1156,23 @@ class Zombie(pygame.sprite.Sprite):
         self.x = float(self.rect.centerx)
         self.y = float(self.rect.centery)
         self.was_in_sight = False
-        self.carbonized = False
         self.age_frames = 0.0
         self.aging_duration_frames = aging_duration_frames
-        self.tracker = tracker
-        self.wall_follower = wall_follower
         if movement_strategy is None:
             if tracker:
-                movement_strategy = zombie_tracker_movement
+                movement_strategy = _zombie_tracker_movement
             elif wall_follower:
-                movement_strategy = zombie_wall_follow_movement
+                movement_strategy = _zombie_wall_follow_movement
             else:
                 movement_strategy = zombie_normal_movement
         self.movement_strategy = movement_strategy
-        self.outer_wall_cells = outer_wall_cells
         self.tracker_target_pos: tuple[float, float] | None = None
         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_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.pos_history: list[tuple[float, float]] = []
         self.wander_angle = RNG.uniform(0, math.tau)
         self.wander_interval_ms = (
             ZOMBIE_TRACKER_WANDER_INTERVAL_MS if tracker else ZOMBIE_WANDER_INTERVAL_MS
@@ -1209,13 +1182,22 @@ class Zombie(pygame.sprite.Sprite):
             0, self.wander_interval_ms + RNG.randint(-500, 500)
         )
 
+    def _redraw_image(self: Self, palm_angle: float | None = None) -> None:
+        paint_zombie_surface(
+            self.image,
+            radius=self.radius,
+            palm_angle=palm_angle,
+            tracker=self.tracker,
+            wall_follower=self.wall_follower,
+        )
+
     def _update_mode(
         self: Self, player_center: tuple[int, int], sight_range: float
     ) -> bool:
         dx_target = player_center[0] - self.x
         dy_target = player_center[1] - self.y
-        dist_to_player = math.hypot(dx_target, dy_target)
-        is_in_sight = dist_to_player <= sight_range
+        dist_to_player_sq = dx_target * dx_target + dy_target * dy_target
+        is_in_sight = dist_to_player_sq <= sight_range * sight_range
         self.was_in_sight = is_in_sight
         return is_in_sight
 
@@ -1231,25 +1213,64 @@ class Zombie(pygame.sprite.Sprite):
         ]
 
         for wall in possible_walls:
-            collides = circle_wall_collision((next_x, self.y), self.radius, wall)
+            collides = _circle_wall_collision((next_x, self.y), self.radius, wall)
             if collides:
                 if wall.alive():
-                    wall.take_damage(amount=ZOMBIE_WALL_DAMAGE)
+                    wall._take_damage(amount=ZOMBIE_WALL_DAMAGE)
                 if wall.alive():
                     final_x = self.x
                     break
 
         for wall in possible_walls:
-            collides = circle_wall_collision((final_x, next_y), self.radius, wall)
+            collides = _circle_wall_collision((final_x, next_y), self.radius, wall)
             if collides:
                 if wall.alive():
-                    wall.take_damage(amount=ZOMBIE_WALL_DAMAGE)
+                    wall._take_damage(amount=ZOMBIE_WALL_DAMAGE)
                 if wall.alive():
                     final_y = self.y
                     break
 
+        for wall in possible_walls:
+            final_x, final_y = self._apply_bevel_corner_repulsion(
+                final_x, final_y, wall
+            )
+
         return final_x, final_y
 
+    def _apply_bevel_corner_repulsion(
+        self: Self, x: float, y: float, wall: Wall
+    ) -> tuple[float, float]:
+        bevel_depth = int(getattr(wall, "bevel_depth", 0) or 0)
+        bevel_mask = getattr(wall, "bevel_mask", None)
+        if bevel_depth <= 0 or not bevel_mask or not any(bevel_mask):
+            return x, y
+
+        influence = self.radius + bevel_depth
+        repel_ratio = 0.03
+        corners = (
+            (bevel_mask[0], wall.rect.left, wall.rect.top, -1.0, -1.0),  # tl
+            (bevel_mask[1], wall.rect.right, wall.rect.top, 1.0, -1.0),  # tr
+            (bevel_mask[2], wall.rect.right, wall.rect.bottom, 1.0, 1.0),  # br
+            (bevel_mask[3], wall.rect.left, wall.rect.bottom, -1.0, 1.0),  # bl
+        )
+        for enabled, corner_x, corner_y, dir_x, dir_y in corners:
+            if not enabled:
+                continue
+            dx = x - corner_x
+            dy = y - corner_y
+            if abs(dx) > influence or abs(dy) > influence:
+                continue
+            dist = math.hypot(dx, dy)
+            if dist >= influence:
+                continue
+            push = (influence - dist) * repel_ratio
+            if push <= 0:
+                continue
+            x += dir_x * push
+            y += dir_y * push
+
+        return x, y
+
     def _avoid_other_zombies(
         self: Self,
         move_x: float,
@@ -1261,7 +1282,7 @@ class Zombie(pygame.sprite.Sprite):
         next_y = self.y + move_y
 
         closest: Zombie | None = None
-        closest_dist = ZOMBIE_SEPARATION_DISTANCE
+        closest_dist_sq = ZOMBIE_SEPARATION_DISTANCE * ZOMBIE_SEPARATION_DISTANCE
         for other in zombies:
             if other is self or not other.alive():
                 continue
@@ -1272,14 +1293,27 @@ class Zombie(pygame.sprite.Sprite):
                 or abs(dy) > ZOMBIE_SEPARATION_DISTANCE
             ):
                 continue
-            dist = math.hypot(dx, dy)
-            if dist < closest_dist:
+            dist_sq = dx * dx + dy * dy
+            if dist_sq < closest_dist_sq:
                 closest = other
-                closest_dist = dist
+                closest_dist_sq = dist_sq
 
         if closest is None:
             return move_x, move_y
 
+        if self.wall_follower:
+            other_radius = float(getattr(closest, "radius", self.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
+                return (
+                    math.cos(self.wall_follow_angle) * self.speed,
+                    math.sin(self.wall_follow_angle) * self.speed,
+                )
+
         away_dx = next_x - closest.x
         away_dy = next_y - closest.y
         away_dist = math.hypot(away_dx, away_dy)
@@ -1302,31 +1336,80 @@ class Zombie(pygame.sprite.Sprite):
         slowdown_ratio = 1.0 - progress * (1.0 - ZOMBIE_AGING_MIN_SPEED_RATIO)
         self.speed = self.initial_speed * slowdown_ratio
 
+    def _update_stuck_state(self: Self) -> None:
+        history = self.pos_history
+        history.append((self.x, self.y))
+        if len(history) > 20:
+            history.pop(0)
+            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:
+            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
+        self.pos_history = []
+
     def update(
         self: Self,
         player_center: tuple[int, int],
         walls: list[Wall],
         nearby_zombies: Iterable[Zombie],
         footprints: list[dict[str, object]] | None = None,
+        *,
+        cell_size: int,
+        grid_cols: int,
+        grid_rows: int,
+        level_width: int,
+        level_height: int,
+        outer_wall_cells: set[tuple[int, int]] | None = None,
     ) -> None:
         if self.carbonized:
             return
+        self._update_stuck_state()
         self._apply_aging()
         dx_player = player_center[0] - self.x
         dy_player = player_center[1] - self.y
-        dist_to_player = math.hypot(dx_player, dy_player)
+        dist_to_player_sq = dx_player * dx_player + dy_player * dy_player
         avoid_radius = max(SCREEN_WIDTH, SCREEN_HEIGHT) * 2
+        avoid_radius_sq = avoid_radius * avoid_radius
         move_x, move_y = self.movement_strategy(
-            self, player_center, walls, footprints or []
+            self,
+            player_center,
+            walls,
+            footprints or [],
+            cell_size,
+            grid_cols,
+            grid_rows,
+            outer_wall_cells,
         )
-        if dist_to_player <= avoid_radius:
+        if dist_to_player_sq <= avoid_radius_sq or self.wall_follower:
             move_x, move_y = self._avoid_other_zombies(move_x, move_y, nearby_zombies)
+        if self.wall_follower and self.wall_follow_side != 0:
+            if move_x != 0 or move_y != 0:
+                heading = math.atan2(move_y, move_x)
+            elif self.wall_follow_angle is not None:
+                heading = self.wall_follow_angle
+            else:
+                heading = self.wander_angle
+            if self.wall_follow_side > 0:
+                palm_angle = heading + (math.pi / 2.0)
+            else:
+                palm_angle = heading - (math.pi / 2.0)
+            self._redraw_image(palm_angle)
         final_x, final_y = self._handle_wall_collision(
             self.x + move_x, self.y + move_y, walls
         )
 
-        if not (0 <= final_x < LEVEL_WIDTH and 0 <= final_y < LEVEL_HEIGHT):
-            final_x, final_y = random_position_outside_building()
+        if not (0 <= final_x < level_width and 0 <= final_y < level_height):
+            final_x, final_y = random_position_outside_building(
+                level_width, level_height
+            )
 
         self.x = final_x
         self.y = final_y
@@ -1346,24 +1429,10 @@ class Zombie(pygame.sprite.Sprite):
 
 
 class Car(pygame.sprite.Sprite):
-    COLOR_SCHEMES: dict[str, dict[str, tuple[int, int, int]]] = {
-        "default": {
-            "healthy": YELLOW,
-            "damaged": ORANGE,
-            "critical": DARK_RED,
-        },
-        "disabled": {
-            "healthy": (185, 185, 185),
-            "damaged": (150, 150, 150),
-            "critical": (110, 110, 110),
-        },
-    }
-
     def __init__(self: Self, x: int, y: int, *, appearance: str = "default") -> None:
         super().__init__()
-        self.original_image = pygame.Surface((CAR_WIDTH, CAR_HEIGHT), pygame.SRCALPHA)
-        self.appearance = appearance if appearance in self.COLOR_SCHEMES else "default"
-        self.base_color = self.COLOR_SCHEMES[self.appearance]["healthy"]
+        self.original_image = build_car_surface(CAR_WIDTH, CAR_HEIGHT)
+        self.appearance = appearance
         self.image = self.original_image.copy()
         self.rect = self.image.get_rect(center=(x, y))
         self.speed = CAR_SPEED
@@ -1372,85 +1441,23 @@ class Car(pygame.sprite.Sprite):
         self.y = float(self.rect.centery)
         self.health = CAR_HEALTH
         self.max_health = CAR_HEALTH
-        self.collision_radius = car_body_radius(CAR_WIDTH, CAR_HEIGHT)
-        self.update_color()
+        self.collision_radius = _car_body_radius(CAR_WIDTH, CAR_HEIGHT)
+        self._update_color()
 
-    def take_damage(self: Self, amount: int) -> None:
+    def _take_damage(self: Self, amount: int) -> None:
         if self.health > 0:
             self.health -= amount
-            self.update_color()
+            self._update_color()
 
-    def update_color(self: Self) -> None:
+    def _update_color(self: Self) -> None:
         health_ratio = max(0, self.health / self.max_health)
-        palette = self.COLOR_SCHEMES.get(self.appearance, self.COLOR_SCHEMES["default"])
-        color = palette["healthy"]
-        if health_ratio < 0.6:
-            color = palette["damaged"]
-        if health_ratio < 0.3:
-            color = palette["critical"]
-        self.original_image.fill((0, 0, 0, 0))
-
-        body_rect = pygame.Rect(1, 4, CAR_WIDTH - 2, CAR_HEIGHT - 8)
-        front_cap_height = max(8, body_rect.height // 3)
-        front_cap = pygame.Rect(
-            body_rect.left, body_rect.top, body_rect.width, front_cap_height
+        color = resolve_car_color(health_ratio=health_ratio, appearance=self.appearance)
+        paint_car_surface(
+            self.original_image,
+            width=CAR_WIDTH,
+            height=CAR_HEIGHT,
+            color=color,
         )
-        windshield_rect = pygame.Rect(
-            body_rect.left + 4,
-            body_rect.top + 3,
-            body_rect.width - 8,
-            front_cap_height - 5,
-        )
-
-        trim_color = tuple(int(c * 0.55) for c in color)
-        front_cap_color = tuple(min(255, int(c * 1.08)) for c in color)
-        body_color = color
-        window_color = (70, 110, 150)
-        wheel_color = (35, 35, 35)
-
-        wheel_width = CAR_WIDTH // 3
-        wheel_height = 6
-        for y in (body_rect.top + 4, body_rect.bottom - wheel_height - 4):
-            left_wheel = pygame.Rect(2, y, wheel_width, wheel_height)
-            right_wheel = pygame.Rect(
-                CAR_WIDTH - wheel_width - 2, y, wheel_width, wheel_height
-            )
-            pygame.draw.rect(
-                self.original_image, wheel_color, left_wheel, border_radius=3
-            )
-            pygame.draw.rect(
-                self.original_image, wheel_color, right_wheel, border_radius=3
-            )
-
-        pygame.draw.rect(self.original_image, body_color, body_rect, border_radius=4)
-        pygame.draw.rect(
-            self.original_image, trim_color, body_rect, width=2, border_radius=4
-        )
-        pygame.draw.rect(
-            self.original_image, front_cap_color, front_cap, border_radius=10
-        )
-        pygame.draw.rect(
-            self.original_image, trim_color, front_cap, width=2, border_radius=10
-        )
-        pygame.draw.rect(
-            self.original_image, window_color, windshield_rect, border_radius=4
-        )
-
-        headlight_color = (245, 245, 200)
-        for x in (front_cap.left + 5, front_cap.right - 5):
-            pygame.draw.circle(
-                self.original_image, headlight_color, (x, body_rect.top + 5), 2
-            )
-        grille_rect = pygame.Rect(front_cap.centerx - 6, front_cap.top + 2, 12, 6)
-        pygame.draw.rect(self.original_image, trim_color, grille_rect, border_radius=2)
-        tail_light_color = (255, 80, 50)
-        for x in (body_rect.left + 5, body_rect.right - 5):
-            pygame.draw.rect(
-                self.original_image,
-                tail_light_color,
-                (x - 2, body_rect.bottom - 5, 4, 3),
-                border_radius=1,
-            )
         self.image = pygame.transform.rotate(self.original_image, self.angle)
         old_center = self.rect.center
         self.rect = self.image.get_rect(center=old_center)
@@ -1477,10 +1484,10 @@ class Car(pygame.sprite.Sprite):
         ]
         car_center = (new_x, new_y)
         for wall in possible_walls:
-            if circle_wall_collision(car_center, self.collision_radius, wall):
+            if _circle_wall_collision(car_center, self.collision_radius, wall):
                 hit_walls.append(wall)
         if hit_walls:
-            self.take_damage(CAR_WALL_DAMAGE)
+            self._take_damage(CAR_WALL_DAMAGE)
             hit_walls.sort(
                 key=lambda w: (w.rect.centery - self.y) ** 2
                 + (w.rect.centerx - self.x) ** 2
@@ -1499,31 +1506,7 @@ class FuelCan(pygame.sprite.Sprite):
 
     def __init__(self: Self, x: int, y: int) -> None:
         super().__init__()
-        self.image = pygame.Surface((FUEL_CAN_WIDTH, FUEL_CAN_HEIGHT), pygame.SRCALPHA)
-
-        # Jerrycan silhouette with cut corner
-        w, h = FUEL_CAN_WIDTH, FUEL_CAN_HEIGHT
-        body_pts = [
-            (1, 4),
-            (w - 2, 4),
-            (w - 2, h - 2),
-            (1, h - 2),
-            (1, 8),
-            (4, 4),
-        ]
-        pygame.draw.polygon(self.image, YELLOW, body_pts)
-        pygame.draw.polygon(self.image, BLACK, body_pts, width=2)
-
-        cap_size = max(2, w // 4)
-        cap_rect = pygame.Rect(w - cap_size - 2, 1, cap_size, 3)
-        pygame.draw.rect(self.image, YELLOW, cap_rect, border_radius=1)
-        pygame.draw.rect(self.image, BLACK, cap_rect, width=1, border_radius=1)
-
-        # Cross brace accent
-        brace_color = (240, 200, 40)
-        pygame.draw.line(self.image, brace_color, (3, h // 2), (w - 4, h // 2), width=2)
-        pygame.draw.line(self.image, BLACK, (3, h // 2), (w - 4, h // 2), width=1)
-
+        self.image = build_fuel_can_surface(FUEL_CAN_WIDTH, FUEL_CAN_HEIGHT)
         self.rect = self.image.get_rect(center=(x, y))
 
 
@@ -1532,32 +1515,13 @@ class Flashlight(pygame.sprite.Sprite):
 
     def __init__(self: Self, x: int, y: int) -> None:
         super().__init__()
-        self.image = pygame.Surface(
-            (FLASHLIGHT_WIDTH, FLASHLIGHT_HEIGHT), pygame.SRCALPHA
-        )
-
-        body_color = (230, 200, 70)
-        trim_color = (80, 70, 40)
-        head_color = (200, 180, 90)
-        beam_color = (255, 240, 180, 150)
-
-        body_rect = pygame.Rect(1, 2, FLASHLIGHT_WIDTH - 4, FLASHLIGHT_HEIGHT - 4)
-        head_rect = pygame.Rect(
-            body_rect.right - 3, body_rect.top - 1, 4, body_rect.height + 2
-        )
-        beam_points = [
-            (head_rect.right + 4, head_rect.centery),
-            (head_rect.right + 2, head_rect.top),
-            (head_rect.right + 2, head_rect.bottom),
-        ]
+        self.image = build_flashlight_surface(FLASHLIGHT_WIDTH, FLASHLIGHT_HEIGHT)
+        self.rect = self.image.get_rect(center=(x, y))
 
-        pygame.draw.rect(self.image, body_color, body_rect, border_radius=2)
-        pygame.draw.rect(self.image, trim_color, body_rect, width=1, border_radius=2)
-        pygame.draw.rect(self.image, head_color, head_rect, border_radius=2)
-        pygame.draw.rect(self.image, trim_color, head_rect, width=1, border_radius=2)
-        pygame.draw.polygon(self.image, beam_color, beam_points)
 
-        self.rect = self.image.get_rect(center=(x, y))
+def _car_body_radius(width: float, height: float) -> float:
+    """Approximate car collision radius using only its own dimensions."""
+    return min(width, height) / 2
 
 
 __all__ = [